(navigation image)
Home American Libraries | Canadian Libraries | Universal Library | Community Texts | Project Gutenberg | Children's Library | Biodiversity Heritage Library | Additional Collections
Search: Advanced Search
Anonymous User (login or join us)
Upload
See other formats

Full text of "VIC Forth (1982)(HES)"

VIC FORTH 



By Tom Zimmer 



FORTH "is" an interactive language.that 
many times faster than BASIC, yet is 
easier to use than assembly language 
FORTH programs are modular permit! 
structuredprogramming and are ex- 
tremely efficient in memory usage. 



VIC FORTH 



nplete implement? 



du tar hta vers 




VIC FORTH is an exciting new cartridge 
for your VIC 20 computer. You now have 
a language that is more powerful than 
BASIC and easier to program than as- 
sembler! Some of VIC FORTH's major 
features are: ability to define your own 
words; this means a function not already 
supported can be created by you and 
added to VIC FORTH for future use. Full 
VIC sound and color capabilities are built 
into VIC FORTH. Names for your words - 
may be up to 31 characters, unlike BASIC. 
which supports only 2 characters. 

VIC FORTH comes with a superb full- 
screen editor which has 16 lines of 64 
characters each (standard FORTH 
screen), using a horizontal scrolling win- 
dow. VIC FORTH is an interactive lan- 



guage that is very memory efficient and 
much faster than BASIC. 

VIC FORTH will run in a standard VIC 20, 
although extra memory is recommended. 
Programs can be loaded or saved from 
tape or disk. Character output can be sent 
to any device, including the VIC printer. Up 
to 24K additional bytes of memory can be 
automatically used in VIC FORTH. VIC 
FORTH is a nearly complete implementa- 
tion of the FORTH INTEREST GROUP 
(fig) version of FORTH. The VIC FORTH 
editor follows closely the standard FORTH 
editor described in the book. "STARTING 
FORTH," plus it has many, many addi- 
tional features. 



HS 



;for' 



VIC FORTH 

By Tom Zimmer 



nstruction Manual 



VIC FCRTH 

By Tom Zimmer 

CONTENTS SUB3ECT PAGE 

1.0 INTRODUCTION 2 

1.1 REQUIREMENTS 2 

1.2 VICFORTH STARTUP 2 

1.3 FIRST IMPRESSIONS 3 

1.4 WHAT IS VICFORTH? 3 

1.5 NEW USER OF FCRTH OR A VETERAN? 5 

1.6 WHAT IS THE FCRTH INTEREST GROUP 5 
2.0 VICFORTH SYSTEM CONFIGURATION 6 

2.1 1VEM3RY ALLOCATION 8 

2.2 BLOCK INPUT/OUTPUT 10 

2.3 SYSTEM CALLS 10 

2.4 CASSETTE INTERFACE 12 

2.5 DOWN-LOADED WORDS 13 

2.6 WHAT IS MISSING 1* 

2.7 NEXT 1* 

2.8 MEMORY MAP 1* 
3.0 EDITOR 16 

3.1 EDITOR COMMENTS 16 

3.2 AN EDITOR EXAVPLE 17 

3.3 EDITOR W3RDS 19 
4.0 VICFORTH SPECIFICS 24 

4. 1 COLOR CONTROL 24 

4.2 SOUND CONTROL 26 

4.3 USER PORT 27 

4.4 PRINTER OUTPUT 28 

4.5 SCREEN BUFFER CONTROL 30 

4.6 VLIST 31 

4.7 ADDITIONAL UTILITIES 32 
5.0 VECTORS 33 

5.1 WHAT ARE THEY? 33 

5.2 VECTORED W3*DS IN VICFCRTH 34 



5.3 VECTOR CONTROL 34 

6.0 ERRORS, CRASHES AND OTHER PROBLEM- 37 

ERRCR IvESSAGES 37 

WHAT DO I DO WEN IT CRASHES? 38 
USAGES 39 

FORTH-79 DIFFERENCES 40 

7.Q VIOFCRTH AND DISK 47 

8.0 USEFUL UTILITIES 49 

9.0 VICFCRTH ALPHABETIZED GLOSSARY 52 

1.0 INTRODUCTION 



6. 


.1 


6. 


.2 


6. 


,3 


6. 


.4 



This manual describes the VICFCRTH system for the 
COvRODCRE VIC-20 computer. It is an extension of 
the FORTH Interest Group (fig) model of the language 
FORTH. 

1.1 REQUIRE\€NTS 

HARDWARE The VIC-20 must have at least 5K 
bytes of memory (which is available on a standard 
VIC-20), and VICFCRTH wi 1 1 automatically adjust to 
more memory if you have it. The 3K ram expansion 
cartridge does not provide any additional memory for 
VICFCRTH to use. 

1.2 VICFCRTH STARTUP 

1. Verify the power is OFF!!. 

*****NEVER INSERT OR REVDVE A CARTRIDGE***** 
***** WITH THE poker ON ! ! ! ! ***** 

2. Plug the cartridge into the slot on the back. 

3. ONLY THEN turn on the power. 

The computer will start up with the VICFCRTH sign on 
message in dark blue characters on a cyan 
background, with a green border. VICFCRTH is now in 
control . 

2 (C) 1982 Human Engineered Software 



1.3 FIRST I^RESSIONS 

After VICFCRTH is started as described previously, 
the FCRTH operating system is running, with its 
compiler, interpreter, and text editor. If you 
press the RETURN key a few times, you will notice an 
'CK' is printed after each RETURN is pressed. FCRTH 
is just telling you that it recognized your request 
to do nothing, and has returned for your next 
corrmand. In FCRTH a line of input text is simply a 
line of commands, each separated by a space, which 
FCRTH recognizes as corrmand separator. Each corrmand 
in the line is performed from left to right. If all 
commands are performed without encountering an 
error, then FCRTH returns with the 'OK' prompt to 
tell you its mission was accomplished. If an error 
is encountered at any time during execution, then 
all processing stops, FCRTH wi 1 1 issue an error 
message and wait for further instructions. 



1.4 WHAT IS VICFCRTH? 



VICFCRTH is an implementation of fig-FCRTH with the 
addition of several words to interface to the VIC's 
sound and color capabilities. Over 250 WCRDs are 
included in VICFCRTH, and since FCRTH is extensible, 
you can add many of your own corrmands to VICFCRTH. 
If you have not used the FCRTH language before, you 
will probably find FCRTH' s syntax to be somewhat 
strange. But don't let that bother you; the FCRTH 
programming environment has been honed over a period 
of 12 years into a very efficient system. In BASIC 
where seme arithmetic operators have different 
precedences, it is sometimes hard to remember which 
functions are performed first. To alleviate this 
problem BASIC uses parentheses to specify the order 

(C) 1982 Human Engineered Software 3 



of operation. FCRTH does not need to worry about 
such things, it uses a straight left to right 
process. 

VICFCRTH also contains words to allow you to control 
the character, border, and background colors of the 
screen. 

Five sound control words are provided to allow 
manipulating the sound output in the VIC-20. 

All I/O and several other words are VECTORED, to 
allow their function to be changed at runtime. This 
will allow you to drive a printer or other device 
using I/O that the system may not know exists. As 
an example, a driver routine could be written to 
drive a parallel printer over the user port. 

In FCRTH the term '\ICRD' refers to an identifiable 
function or command, which in some computer 
languages is referred to as a subroutine or 
procedure. 

In VICFCRTH «CRDS may be any length from one to 
thirtyone characters in length. This allows very 
descriptive names to be used in writing your 
programs. FCRTH programs can then be much easier to 
read, than basic. It is important to note however 
that program readability is the responsibility of 
the person wr it ing the program, and it is just as 
easy to write programs with all single character 
names, thus making them almost impossible to 
decipher. The use of readable names for your 
VICFCRTH words is highly recommended. 



(C) 1982 Human Engineered Software 



1.5 NEW USER CF FORTH CR A VETERAN 

We wish to state very clearly that this manual is 
NOT A FCRTH BEGINNERS MANUAL! ! . If you are a 
newcomer to the FORTH world, VICFCRTH provides all 
of the program tools you will need to learn the 
FORTH language, BUT there are several books which 
you should purchase that will better lead you in 
learning the FORTH language. These books are as 
fol lows: 

1. STARTING FORTH 

2 . f i g-FCRTH I NSTALLAT ION MANUAL 

3. f ig-FCRTH 6502 ASSEMBLY SOURCE LISTING 

4. FCRTH- 79 STANDARD CONVERSION 

The first two are highly reconrmended, and wi 1 1 
provide you with most of the needed tutorial 
information. All of these manuals are available 
from the FCRTH INTEREST GROUP. 

Another point worth stressing is that the STARTING 
FCRTH manual listed above is the best tutorial 
manual available today, BUT it describes a version 
of FORTH called FORTH-79, which is not identical to 
fig-FCRTH/VICFORTH. So you should read the section 
of this manual called FCRTH-79 DIFFERENCES while 
using the book, to assist you in learning FCRTH. 
Also, the publication FCRTH-79 STANDARD CONVERSION 
will be helpful in running the more complex examples 
in the STARTING FCRTH book. 

1.6 WHAT IS THE FCRTH INTEREST GROUP 

The FCRTH INTEREST CROUP is an independent group of 
FORTH enthusiasts whose aim is to educate others, 
answer technical questions and to promote FORTH. 

(C) 1982 Human Engineered Software 5 



They may be contacted at: 

PO Box 1105 Phone for orders: 

San Carlos, CA 94070 (415) 962-8653 

They publish a newsletter FORTH D 1 1VENS IONS ($15/yr) 
and have many other publications available. 



2.0 VICFORTH SYSTEM CONFIGURAT ION 

The following describes some of the aspects of how 
the VICFCRTH system is organized and how it is 
similar and/or dissimilar to other FORTH systems. 

NOTICE!!! If you are a complete beginner to 
FORTH, you should probably skip this section for 
now, and go to the book STARTING FORTH which you 
should have purchased. Just start working through 
the book. Do not be afraid of experimenting! The 
program in the cartridge can not be damaged by any 
programming error. Just press RUN/STOP RESTORE to 
restart if required. 

NOTATION The following symbol terminology is used 
throughout this manual. The L sign is used in place 
of the # sign, ie the one above the 3 key. 

SYMBOLS LEANING 

al or addrl 16 bit address 

n, nl, or n2 16 bit signed number 

dl, d2 32 bit signed double number 

ul, u2 16 bit unsigned number 

bl 8 bit byte 

c, cl 7 bit ascii character 

f, fl Boolean flag 

6 (C) 1982 Human Engineered Software 



tf 


ff 


string, t 


<sp> 


<return> 


STACK VALUES 



True boolean flag -- 1 
False boolean flag -- 
Ascii text string 
Space character 
The RETURN key 

(b — t ; a) 

b The stack before the word executes. 

— The word being executed. 

t The ascii string which follows the word 
in some cases. 

; Denotes the place where the <return> 
key would be pressed. 

a The stack after the word executes. 

STACK PARAVETER DESCRIPTIONS 

nl/n2/n3 

The value nl was placed on the stack first, 
then n2, then n3. The notation is read "nl under n2 
under n3". n3 is on top of the stack. 

EXAVPLE: 

In the description of a FORTH word called 
<example>, the following might appear: 

al/nl/n2 --- t ; a2 

This would be interpreted as follows: 
Before the word <example> is executed there are 
three items on the stack with n2 being the last 
placed on, nl being the previous one, and al being 

the earliest one. The ' ' represents the word 

<example> being executed, where 't' is text which 

(C) 1982 Human Engineered Software 7 



must follow <example> before <return> is pressed at 
the ';' symbol. After the execution of the word 
<exarrple>, the stack is left with one item 'a2'. 

2.1 ME1VDRY ALLOCATION 

VICFCRTH will run on any OTMvODCRE VIC-20 computer 
with 5K to 29K bytes of user read/write (ram) 
memory. About 2K bytes of the available ram is used 
by the system, (FORTH <5c the KERNEL) so in a 5K 
VIC-20 this leaves about 3K bytes for the users 
program. The available ram is then divided into two 
segments. The first segment is screen/block buffer 
space; this area holds the source text for any 
program you enter. The second segment is called the 
dictionary; it holds the object code of any program 
you have compiled. 

On a 5K VIC, VICFCRTH will initialize itself with 2K 
bytes allotted to screen buffer space (which is 
equal to two screens), and IK bytes for dictionary 
space. Since a compiled program is generally much 
smaller than the source which created it, a two 
screen (2K) source program should compile into IK of 
dictionary space without difficulty. 

There can, however, occur situations where you would 
like to have more than IK of dictionary space. If 
this occurs, you can resegment the user ram with the 
system word "tBLCGKS". This word allows you to 
specify how many screens of buffer space you will 
have in the system. Any reduction in screen buffer 
space results in an increase in dictionary or 
compiled program space. The following corrmand will 
allot one screen buffer, and return an additional 
1024 bytes of ram to the dictionary. 



(C) 1982 Human Engineered Software 



1 <sp> LBLOCKS <return> 

The LBLOCKS corrmand clears out any program in the 
dictionary before resegmenting the user ram, so any 
program already compiled will be lost, effectively a 
COLD start is performed. The LBLOCKS corrmand is 
normally executed right after powerup. 

If your VIC-20 has more than 5K bytes of ram 
(excluding the 3K ram cartridge, which VICFCRTH 
cannot access), VICFCRTH will automatically expand 
the number of screen buffers up to six screens. A 
screen in VICFCRTH is 1024 characters, or bytes of 
memory. In a fully expanded VIC-20 with 29K bytes of 
user memory, you may specify up to 26 screen 
buffers, to allow editing very large programs. 

The corrmand LBLOCKS always truncates the number of 
screens you request to within the range one to the 
maximum that memory will allow minus one; this 
assures there will always be at least IK bytes of 
dictionary space. 

2.1.1 STACK SPACE 

The system stacks are located near the bottom of 
memory. The DATA stack is located in page zero , 
from about $60 (numbers preceded by $, like $60, 
indicate a hexadecimal number) down to $10, giving 
room for about 40 data stack entries. The RETURN 
stack is located in page one, the 6502 hardware 
stack. It shares this page with the terminal input 
buffer, and is thus limited to about 60 decimal 
levels of nesting. These stacks should be large 
enough for any properly developed program. 



(C) 1982 Human Engineered Software 



2.2 BLOCK INPUT/OUTPUT 

The word BLOCK in the language FORTH provides the 
user with a method of accessing a very large data or 
program storage area typically on disk, as if all of 
the storage area were in the user ram memory space. 
In VICFCRTH where a disk is typically not available, 
this process is simulated by allocating an area of 
user memory for the virtual screen buffers, and 
limiting the range of the area a user can access to 
the amount of screen buffer space currently 
specified. This technique allows many of FORTH' s 
virtual memory operations to be performed normally, 
but within the restriction of user memory. The 
BLOCK corrmand is a member of the list of vectored 
words in VICFCRTH, and it's definition can be 
changed by the user. 

In a disk based FORTH system the word BLOCK just 
described would perform the reads and writes to disk 
automatically. In this cassette-based system 
however, screens are read or written to cassette by 
the user using the READ and WITE words described 
later in this chapter. 

2.3 SYSTEM CALLS 

CCMVCDCRE has built into the VIC-20 a very powerful 
KERNEL. In BASIC, you do not have access to the 
KERNEL , since it must be passed several parameters 
in the machine registers to control the operation of 
a KERNEL call. In VICFCRTH, however, a word 'SYS' 
has been provided which allows you to set all of the 
machine's registers including the status of the 
CARRY FLAG, before performing a system call. Once 
the call returns, the contents of all CPU registers 
is placed on FORTH' s stack, and is available to you. 
This very versatile word allows you to access all 



10 



(C) 1982 Human Engineered Software 



KERNEL functions from high level FCRTH. 

SYS (<f>/nl/n2/n3/al — - <f>/n4/n5/n6 ) 
The SYS command allows calling any assembly language 
routine, 'f is an optional CARRY set/reset flag; it 
is returned unmodified, nl, n2, and n3 are the A,X,Y 
registers respectively, and return their routine 
modified contents, al is the call address. Any 
called routine must return with an assembly 'RTS' 
instruction, and must not destroy the hardware stack 
contents. Here is an example of a system call to the 
VIC KERNEL: 

HEX 

: MESSAGES .OFF FF90 SYS 3DRCP ; 

This word will turn off all KERNEL messages, for 
errors, and warnings, etc. VICFCRTH is initialized 
with all messages CN. The "0 0" in the above 
definition are the manditory "A,X,Y" register 
values. The address "FF90" is the call address for 
the system call we are performing. The word SYS 
performs the system call, and the 3DRCP after SYS 
removes the returned values of the "A,X,Y" registers 
after the call is performed, off the stack. 

Here is a list of predefined system calls available 
in VICFCRTH. 

SETFLS (nl/n2/n3 ) Set system logical file 

command, must be sent nl, the user assigned fileL, 
n2 the device number assigned to the filet, and n3 
the corrmand to be sent to the device. See the " VIC 
PROGRAMMERS REFERENCE MANUAL" . 

OPEN ( — ) Open the device and fileL 
specified in the previous SETFLS corrmand. 

(C) 1982 Human Engineered Software 11 



SAVE ( al/nl ) Save to cassette from memory 

at address al, for a count of nl bytes, as the file 
last specified by SETFLS. 

SLOW ( al — ) Load from cassette to memory 
at address al, the file last specified by SETFLS. 
The load buffer area must be large enough for the 
file being loaded. 

CrKOUT ( nl ) Send all character output to 

device nl. Device nl must have been previously 
opened. 

CLALL ( --- ) Clear all channels and 
devices, restore all I/O to video and keyboard. 

SETNAW ( al/nl --- ) Set the name at address 'al', 
as the current file name, for a length of 'nl' 
characters. See also section 7.0, VICFCRTH AND 
DISK. 

2 A CASSETTE INTERFACE 

Five words have been included in the system to 
permit easy writing and reading of data to and from 
cassette. These are: 

READ ( nl — ) 

READS ( nl/n2 — - ) 

VtRITE ( nl --- ) 

WRITES ( nl/n2 -- ) 

In these words, nl is the first SCREEN or BLOCK to 
read or write. n2, when present, is the number of 
SCREENS or BLOCKS to read or write. 



12 (C) 1982 Human Engineered Software 



DON'T FORGET TO SETUP THE CASSETTE RECORDER! 

The fifth word is - 

LOADS ( nl — ) 

nl screens will be loaded from cassette, and 
compiled or interpreted. Each SCREEN wi 1 1 be read 
into BUFFER £1, and then a 1 LOAD is performed. Then 
the next SCREEN is read and loaded, etc. This 
procedure was chosen so that only a single buffer 
would be required, in order to have the system 
function with minimal memory. This means that very 
large programs may be loaded. The number nl 
specifies the number of screens to be read and 
loaded, and it must match the actual number of 
screens on the cassette. 

Two additional words direct the device number, and 
the file number to be used with READ and WRITE 
operations. These are "D£" and "F£". They are 
initialized to 1 by VRESET, for normal cassette 
operation. If you wish to direct READ/WRITE I/O to 
a device other than cassette, you will need to 
change the contents of these variables. See also 
section 7.0 on VICFCRTH DISK OPERATION. 

2.5 DOWI-LQADED VtCRDS 

Two words in VICFCRTH are DOWN-LOADED to RAVI from 
ROM. They are: 

FORTH and EDITOR 

These two words are what are called VOCABULARIES. 
They contain a variable which changes as new words 
are added to the dictionary. For these variables to 

(C) 1982 Human Engineered Software 13 



function correctly they mist be in RAW, so both of 
these words are DCWN-DOADED. The total code that is 
moved is less than 60 bytes. 



2.6 1AT IS MISSING 

There are several fig-FORTH words which are not in 
this system. For the most part these are words which 
are used for the DISK interface. They are not 
needed in this implementation. They are: 

BUFFER +BUF R/W INDEX TRIAD PREV USE 
FLUSH UPDATE EVPTY-BUFFERS (AECRT) WARNING 

If desired, an EXPERIENCED PROGRAMVER can add these 
and change the VECTOR for BLOCK. 



2.7 NEXT 

For those interested assembly language prograrrmers, 
NEXT is located with the following code sequence: 

' (LOOP) NFA 2 - (cl CONSTANT NEXT 

Here a constant has been created with the name NEXT 
for future program reference. 

2.8 MEMORY M\P 

$0000 
$0060 SO 



FCRTHS DATA STACK 
VIC SYSTEM DATA AREA 
TIB / RETURN STACK 
** (C) 1982 Human Engineered Software 



$0100 TIB 



I 



VIC WORKING STORAGE AREA 



3K EXPANSION AREA 
(not used by VICFCRTH) 



i 

! SCREEN RAM IN EXPANDED SYSTEM 

! DOWN LOADED FORTH W3RDS 



USER TABLE AND VECTORS 
FIRST SCREEN/BLOCK BUFFER 



ADDITIONAL OPTIONAL BUFFERS 
UP TO THE MAX ALLOXED BY MEM 



USER DICTIONARY RAM AREA 



-$01FF RO 

[ 

-$owo 



-$1000 

! SCREEN 

i 

■-$1220 



■-$1260 UPO 

i 

-$1340 
1FIRST 



Memory end is specified in variable EM 



- DPO & 
! LIMIT 
! 5K= 

! $1B48 

! 13K= 

! $2B56 

- EM($283) 




$A000 



$BFFF 



(C) 1982 Human Engineered Software 



15 



3.0 EDITCR 



3.1 EDITOR. COMMENTS 



The EDITCR in VICFCRTH is modeled after the editor 
described in the introductory book STARTING FORTH by 
L. Brodie. 

Note: For the examples in the book STARTING FORTH 
and the discussion in this manual, use screens 
numbered 1 to 6 on an 8K expanded system, or screens 
1 and 2 on a nonexpanded system. 

You can now start the edit session by entering the 
fol lowing: 

nl <sp> EDIT <return> 

The EDITCR vocabulary is selected and the BACKGROUND 
color has switched to WHITE, indicating the editor 
has been selected. The screen will be split in two - 
the top 16 lines are used for entering text (edit 
area) and the bottom 6 for entering edit commands 
(conrmand area). If you just turned on the computer, 
you will have 16 lines of garbage at the top of the 
screen. To clear out the edit buffer in preparation 
for editing, type: 

WIPE <return> 

This will clear the edit screen to ail spaces. While 
in the editor, the window around the cursor is 
always displayed just before the next command line 
is fetched from the keyboard, so you always have an 
updated view of what your edit commands are doing to 
the text. You will also notice two double-digit 
numbers displayed in the lower right corner of the 
edit window. The rightmost number is the column 

16 (C) 1982 Human Engineered Software 



position of the cursor in the edit screen, the left 
number is the number of the current edit screen. The 
cursor keys are also redirected in the editor, so 
they allow you to scan around through the edit 
screen with very little effort. To leave the EDIT 
mode, just press RUN/STCP RESTORE, and the edit mode 
will be terminated. 

For a complete discussion of the use of the editor 
commands you should refer to the book STARTING 
FORTH, although it is similar enough to a typical 
fig-FORTH editor that an experienced FORTH 
progranmer should be able to use the editor with 
just the abbreviated discussion presented in the 
next section. 

Note: Three characters are viewed incorrectly in 
the edit window. 

[ is -f ] is | @ is — 

3.2 AN EDITOR EXAMPLE 

This editor contains both Screen and Line edit 
conrmands. The line edit commands have been taken 
directly from STARTING FORTH, and are described in 
that book. The screen edit commands give you the 
ability to see the form of the text as it is entered 
into the edit screen. To enter the screen edit 
mode, press the <shift> key, and the <INST/DEL> key. 
The border of the screen will switch to yellow 
(lighter grey on a b/wTV), and is now waiting for 
you to type any text you wish inserted into the 
screen. Type the following: 

THIS IS VICFCRTH <F5> 

(C) 1982 Human Engineered Software 17 



The text THIS IS VICFCRTH was inserted in line zero 
of the screen, and when you pressed <F5> (F5 is the 
tan function key labeled F5), the cursor moved to 
the beginning of the next line. The <F5> function 
key is like <return>, in that it moves the cursor to 
the next line, but it leaves you in the INSERT mode. 
If you accidentally pressed <return>, you wi 1 1 have 
noticed the border switch back to OREEN, indicating 
you have left the INSERT mode. To repeat, you must 
press <return> to exit the INSERT mode, at which 
time the border will switch back to the normal 
GREEN. While in the INSERT mode, the <del> key is 
enabled to delete characters before the cursor in 
the edit window, rather than characters on the 
comnand lines at the bottom of the screen. 

3.2.1 AN EDITCR EXAMPLE (contd) 

Type in the following edit corrmands in the edit mode 
to get a feel for the different edit corrmands. 

1 EDIT 

WIPE 

3 T 

P THIS IS A LINE OF TEEXT 

K 

P THIS IS A LINE CF TEXT. 

U HERE IS ANOTHER ONE 

3 T 

F TEXT 

E 

5 T 

P THIS IS AANOTHER ONE ONE. 

F AANOTHER 

R ANOTHER LINE 

D ONE 



18 (C) 1982 Human Engineered Software 



1 DEL 

4 T 
F A 

TILL ER 
8 T 

P HERE IS A TEST LIST 
F LIST 
E 

8 T 

D TEST 
I NEW LINE 

3 T P EXAWLE CF TWO CCMv¥\NDS 
X 
To leave the editor, type one of the following: 

FCRTH ( Terminate the session ) 
VRESET ( Reset all I/O vectors ) 

— or — 

hit RUN/STO? & RESTORE (Reselects FORTH and resets 

I/O vectors) 

3.3 EDITOR WCRDS 



LINE EDITING QO\M\NDS 
From STARTING FORTH editor: 

WORD FUNCTION 

T ( nl — ) Sets the edit pointer to the start 
of 1 ine nl . 

P ( — <t> ; ) Text following space after P is 
placed into line holding edit pointer. 



(C) 1982 Human Engineered Software 19 



U ( — <t> ; ) Text following space after U is 
placed under the current line and all lower lines are 
moved down. 

M ( nl/n2 ) Copies current edit pointer line 

UNDER line n2 in screen nl. 

X ( — ) Deletes line containing the edit 
pointer and moves lower lines up one. Line L15 
becomes blank. The line is held in PAD I. 

Added from fig editors; 

H ( — ) Holds the edit pointer line in PADI. 

K ( — ) Kills (erases) the edit pointer line. 

S ( ) Spreads the lines at the edit pointer. 

All lines from the edit pointer are moved down. 
Line 15 is lost. 

TCP ( — ) Move edit pointer to TCP of screen. 

NOTE: In ( --- <t> ; ), The <t> symbol indicates the 
text is optional. Typing <return> without any text 
will use the current contents of PADI, or PADF. 

EDITING COMMANDS 

From STARTING FCRTH editor: 



ViCRD FUNCTION 



F ( — <T> ; ) Find first occurance of text 
following 'F' . Starts at current edit pointer. 



20 (C) 1982 Human Engineered Software 



E ( — ) Erases as many characters going 
backward as the length of the last 'F' conmand. 

D ( ) Deletes the first occurance of 

text following the D conrmand, searches from edit 
pointer till end of screen. 

TILL ( — <t> ; ) Deletes all text starting at 
edit pointer until and including the string 
following the conrmand TILL. Works on current LINE 
only. If string is not found, no delete occurs. 

I ( — <t> ; ) Inserts text following the 
conmand I into the edit buffer at the current 
position of the edit pointer. Text following that 
is too long for the line is lost. 

R ( — <t> ; ) Replaces the string just found 
by 'F' with the string following the R conmand. 

Additions to the editor: 



DEL ( nl --- ) DELetes nl characters BEFCRE 
the edit pointer, and compresses the line to omit 
the space. 

C ( nl — ) Move the cursor by the signed 
amount nl characters (positive for forward move, 
negative for backward move). This word also 
redisplays the current edit window. 

N ( — ) Move the edit pointer to the top 
of the next higher screen buffer. Limited by BMAX. 

B ( — ) Move the edit pointer to the top 
of the previous (lower) screen buffer. Limited by 



(C) 1982 Human Engineered Software 21 



BM\X. 

EDIT ( nl ) Selects the edit mode, with 

nl as the screen to be edited. Moves the edit 
pointer to the top of screen nl. Revectors OR & KEY 
to show the current edit window, and make cursor 
keys functional. 

MISCELLANEOUS EDITOR W3?DS 

These words are not normally used from the keyboard. 
They are provided to allow editor expansion. 

(F) ( --- ) Search for text in PADF till end of 
screen. 

(I) ( — ) Insert the current contents of PADI 
into the edit buffer at the cursor. Text too long 
for the line is lost. 

PADF ( — al ) Returns address of find buffer. 

PADI ( — al ) Returns address of insert buffer. 

PAD ( — al ) Returns address of scratchPAD 
area al. 

TEXT ( cl t ; ) Accepts the text following 

the corrmand TEXT into the scratchPAD area until the 
character with ASCII value cl. 

GTEXT ( al ) Accepts text from input 

stream until a delimiting ^ is found, or the 
<enter> key is pressed. The text is placed at 
address al. 

!CUR ( nl ) Sets the edit pointer to 

22 (C) 1982 Human Engineered Software 



value nl. (nl is limited to <= nl <= 1023.) 

Additional in-mediate key functions: 

Cursor keys Active, allow scanning through 
the edit buffer character by character, or with auto 
repeat. 

HCM5 key Moves the cursor to the top of 

the edit screen. 

Function keys: 

Fl Tab cursor right k characters. 

F3 Tab cursor left k characters. 

F5 Move cursor to beginning of next line. 

F2 Move edit to the Next higher screen number. 

F4 Move edit Back to the previous screen number. 

F7 Find the next occurance of search string 
given by the last 'F' corrmand and leave insert mode 
if not found. 

F8 Replace the most recently found string with 
the text specified in the most recent 'R' corrmand. 

<INST> This key enables the INSERT mode, the 
BORDER color is changed to YELLOW to indicate the 
insert mode, and all keys are inserted into the edit 
screen as they are typed. The <DEL> key is also 
enabled, to delete characters on the edit screen 
preceeding the cursor. The <return> key leaves the 
INSERT mode, and the BORDER color returns to GREEN. 

(C) 1982 Human Engineered Software 23 



4.0 VICFCRTH SPECIFICS 

4.1 CQLCR CONTROL 

VICFCRTH provides you with words to control the 
background, border, and character color of the 
VIC-20, without having to poke into memory using an 
obscure calculation. The background is controlled 
as follows: 

nl <sp> BOROUND <return> 

Where nl is a number in the range to 15, giving 16 
possible background colors. The border is 
controlled as follows: 

nl <sp> BORDER <return> 

Where nl is in the range to 7, giving 8 possible 
border colors. The border colors are the same as the 
character colors, listed on the front of the top row 
of keys. Just subtract one from the key number to 
select the proper color. EX/WPLE: 

7 <sp> BORDER <return> 

The above conrmand will select a YELLOW BORDER color. 

The character color is selected in the same manner 
as BASIC. Press the CTRL key, and the color key 
(1-8), to select the character color you desire. The 
color key pressed is also placed in the command 
stream, although it is not a printable character. 
To select the color of characters to be printed 
during program execut ion, first find out what the 
KEY value is for the color desired, as follows: 



24 (C) 1982 Human Engineered Software 



KEY <return> 

^2 ( the up arrow two is CTRL 2) 

<return> (will print the value of the key ) 
5 ( printed by the computer as the value ) 
( of the control 2 key. ) 

Now all that is required since we know the value of 
the key to select the color we want, is to EMIT it: 

5 EMIT <return> ( this will select WHITE 
characters, ) 

( this can be put in a program too! ) 

To switch colors to another color, simply EMIT the 
value for that color. 

Color word glossary: 

BCROUND ( nl --- ) The value nl in the range 
to 15 sets the BackCRCUND color of the screen. 
Refer to the VIC-20 Users Manual for color value 
selection. 

BORDER ( nl ) The value nl in the range 

to 7 sets the BORDER color. The value of nl is the 
same as the keyboard keys 1-8, minus one 1, i.e., 7 
is YELLCW and 2 is RED. 

EMIT ( nl --- ) Sends ASCII value nl to 
the current output device (usually the screen). See 
Appendix J of the VIC User Manual for possible 
values. The values to EMIT to select the different 
character colors are: 



BLK = 


144 


WHT = 


5 


RED = 


: 28 


PUR = 


156 


CRN = 


30 


BLU = 


: 31 



(C) 1982 Human Engineered Software 25 



CYN = 159 YEL = 158 

By the way, the SOREEN in VICFCRTH is always located 
at $1000, regardless of how much memory your system 
has. 



4.2 SOUND CONTROL 

Words have been included to control the VOLUVE and 
frequency of all four of the VIC-20's voices. The 
VOLUVE is controlled as follows: 

nl <sp> VOLUVE <return> 

The value of nl'is used to select the volume of all 
voices currently active. Values to 15 are valid. 

The frequency of the four voices are controlled by 
storing values into the name of the voice to be 
turned on. The names are 

ALTO TENOR SOPRANO NOISE 

The voice is turned on by storing a value greater 
than 128 decimal into the desired voice. Values 128 
to 254 generate increasingly higher frequencies, 
while a value of 255 wi 1 1 generate the lowest 
frequency for a given voice. To generate a middle C 
on the TENOR voice, enter the following: 

10 <sp> VOLUVE <return> 

195 <sp> TENCR <sp> C! <return> 

If the volume is turned up on your television, you 
will hear a note being generated. To turn OFF the 
voice, simply store a zero into it: 

26 (C) 1982 Human Engineered Software 



<sp> TENOR <sp> C! <return> 

The voice will be silenced. 

Sound control glossary: 

VCLUVE ( nl --- ) Sets the VCLUVE of all 
voices as the value of nl. nl is in the range to 
15. 15 is loudest and turns all voices off. 

ALTO 

TENCR 

SOPRANO 

NOISE ( al ) Constants which return the 

address al of the tone voices of the VIC-20. Each 
voice is programmed for frequency by storing an 8 
bit value in the range 128 to 255 into its address. 
EXAVPLE: 

195 <sp> TENCR <sp> C! <return> 

The above will turn on the middle voice of 
the VIC-20. Any value less than 128 will turn off 
the voice. 

» . 3 USER PORT 

CCMVCDCRE has provided a full 8 bit port in the 
VIC-20, and we have included a constant which 
returns the address of the DATA register of that 
port. The name of the word is UPCRT, and it can be 
used to access 8 bits of external data. This port 
is initialized as an INPUT port, so any TTL level 
can be observed as follows: 

UPCRT <sp> C@ <return> 
(C) 1982 Human Engineered Software 27 



This will place the value of the data on the port on 
the FCRTH data stack. Once the data is on the stack, 
it can be printed, or manipulated in many ways. If 
you wished to use the UPCRT as an OUTPUT port, you 
will have to initialize UPCRT as follows: 



255 <sp> UPCRT <sp> 2+ <sp> C! <return> 

This stores a binary value of all ones into the 
UPCRT data direction register of the 6522 VIA chip 
in the computer. The VIA is designed to make any 
data bits output, when the corresponding bits have 
been set to one in the data direction register. 

To control the output data from the port: 

nl <sp> UPCRT <sp> C! <return> 

Where nl is a number in the range to 255, which is 
to be sent to the user port. 

User port glossary: 

UPCRT ( al ) Returns the address al of 

the user port. 

kA PRINTER CUTPUT 



VICPGRTH includes words to allow data or programs to 
be listed to the serial printer. The word PRINT 
allows any character output from the line of text 
following PRINT to be sent to the serial printer, 
then after that line is interpreted, output returns 
to the video screen. A lower level word PRON turns 



28 (C) 1982 Human Engineered Software 



on the printer port, and leaves all character output 
going to the serial printer, till a CLALL (clear 
all) corrmand it executed. These corrmands would be 
used within your program to control printer output. 

To list a screen to the printer: 

PRINT nl LIST 

where nl is the desired screen number. 

Since all I/O is vectored in VICFCRTH, it is also 
possible to write a printer driver for other types 
of printers than are supported by the VIC KERNEL. 
Vectored I/O will be discussed in a later section. 



Printer output glossary: 

PRON ( — ) Send all character output to the 
printer port. 

CLALL ( — ) Restore all KERNEL I/O to their 
default values - keyboard and video. 

PRINT ( — t ; ) Any character output from the 
line of text following the PRINT corrmand, will be 
channeled to the printer port. When the line 
completes interpretation, output will be restored to 
the video. 

NOTE: If an ERROR is encountered in the PRINT 
corrmand line, all character output will remain on 
the printer. To restore character output to the 
video screen, type: 

CLALL <return> 

(C) 1982 Human Engineered Software 29 



This will clear the print buffer, and return 
character output to the video screen. 

NOTE: DO NOT USE THE PRINT VOID FROM WITHIN THE 
EDITOR !! The CR word is revectored by the editor, 
and will cause your listings to be printed without 
carriage returns. 

4.5 SCREEN BUFFER CONTROL 

Memory is a precious corrmodity in a small computer, 
and it needs to be used efficiently. In line with 
this, VICFCRTH includes a method of reallocating use 
memory such that efficient use can be made of the 
limited resources available. Three words are 
provided to control memory usage. They are: 

BM*\X EMPTY EBDOCKS 

BMVC is a user variable, which contains the highest 
block number the system will allow you to access. 
It is initialized at COLD start to a value of six on 
a 13K system, and two on a 5K system. Due to memory 
restrictions a 5K system is limited to 2 screen 
buffers. The following applies to larger machines. 
A 13K machine can have up to 10 screen buffers, 
which leaves very little for program compi lation, 
but which allows large programs to be edited. To 
select a different number of screen buffers than is 
set at COLD start, perform the following: 

7 <sp> LBLOCKS <return> 

The system now is configured for seven screen 
buffers, with the dictionary space reduced 
accordingly to four. IBLOCKS first sets the value 



30 (C) 1982 Human Engineered Software 



of BMAX, after limiting it to the amount of memory 
you have, then calls EJVPTY to reset memory, and 
empty out the dictionary of any current program. 

The word E1VPTY can also be used from the keyboard, 
when you have been experimenting with some new 
definitions, and you would like to clean out the 
dictionary. 

Screen buffer control glossary: 

BIVKK ( — al ) A user variable which 
contains the highest block the user can currently 
access. 

EMPTY ( --- ) Resets the VOCABUL/ARY 
pointers to their GOLD start values, and resets the 
dictionary pointer to LIMIT. 

LBLOCK5 ( nl --- ) Select nl as the current 
number of screen buffers for the system. Limits nl 
to the range 1 to max that memory will allow. 

4.6 VLIST 

The word VLIST in VICFCRTH as in fig-FCRTH gives you 
a list of all of the corrmands currently available. 
The word is executed by simply typing its name: 

VLIST <return> 

You will then see a vertical list of words, each 
having an address to its left. The address is the 
Parameter field address of the word, and can be 
useful in experimenting with VICFCRTH's internals. 
If you press any character key on the keyboard, the 
scrolling list of words will pause until another key 

(C) 1982 Human Engineered Software 31 



is pressed or RUN/STOP is pressed to cause the VLIST 
to stop. 



4.7 ADDITIONAL UTILITIES 



Here are some additional utility definitions 
contained in VICFCRTH. 

DUVP ( al/nl --- ) This utility is provided 
to allow you to dunp the contents of memory to the 
screen in a byte format. The contents of memory are 
printed in the current base, with four numbers per 
line and an address to the left. An example 
fol lows: 

HEX <return> 
AOOO 8 DUVP <return> 
A000 XX XX XX XX 
A004 XX XX XX XX 

Where al is the starting address of the DUVP, and nl 
is the number of characters to display. 

THRU ( nl/n2 — ) Screens numbered nl 
through screen n2 are all loaded in sequence, from 
the memory buffers. These screens must have all 
been previously read in from cassette. 

ASCII ( — t ; ) The first letter of the 
text word following will be placed on the stack when 
in the interpret mode, or compiled into the 
dictionary if in the compile mode. 

EM ( — al ) This is a system 
variable, which returns the address in memory where 
the end of memory pointer resides. Here is a simple 

32 (C) 1982 Human Engineered Software 



definition to calculate the amount of free memory in 
the dictionary and print that value: 

: .FREE EM @ HERE - . ; 

U. ( nl ) Prints the value of nl 

unsigned. 

H. ( nl — ) Prints the value of nl as 
an unsigned hexdecimal value. 

5.0 VECTORS 

5 A WiAT F8E THEY? 

As you may have learned by now, FCRTH is a macro 
language, that is, FCRTH is made up of many simple 
words written in assembly language. These are used 
to create powerful words, by stringing several 
smaller words together in a line. This simple 
technique makes FCRTH a very powerful tool in 
writing programs. There is one small problem with 
this method though - there are times when a low 
level word needs to perform a slightly modified 
function, so a higher level word can also do 
something a little differently. As an example, 
suppose you had a parallel printer. Since the VIC-20 
has an 8 bit user port, it would be nice to be able 
to send all of your listings to that port, rather 
than the video screen. The only problem with this is 
that the VIC-20 KERNEL doesn't know about your 
printer on the USER port, and can not easily be made 
to talk to it. In VICFCRTH this will not be a major 
problem. All I/O in VICFCRTH is vectored, so you can 
make all character output from FCRTH go to your own 
routine rather than just the routines that the 
VIC-20 already knows about. 

(C) 1982 Human Engineered Software 33 



3.2 VECTORED VOIDS IN VICFCRTH 

VICFCRTH has included a minimum set of words which 
should fill the needs of most users wishing to 
revector various operations in FORTH. Here is a 
list of all of the VECTCRed words in VICFCRTH, and 
their positions in the two vector tables, I/O, and 
WORDS. 

Position Word 
HEX DECIIVAL 



00 


00 


KEY 


02 


02 


EMIT 


04 


04 


7TERMINAL 


06 


06 


CR 


08 


08 


CREATE 


0A 


10 


NUMBER 


0C 


12 


ERRCR 


0E 


14 


. (dot) 


10 


16 


-FIND 


12 


18 


^SSAGE 


14 


20 


BKXK 


16 


22 


EXPECT 


18 


24 


CTBL 



Note: User created vectored words start at an 
index of 30, and may consist of up to 20 total 
vectors, two bytes each. 
3.3 VECTCR CONTROL 

Here is an example of how to revector the character 
output to a different device than the video screen. 



34 (C) 1982 Human Engineered Software 



We will give an example of a printer driver for the 
USER port, for a seven (7) bit printer driver, with 
the eighth (8th) bit used as a strobe. 

The first thing we need is a word to initialize the 
port for all 8 bits as outputs: 

( ) ( initialize the user port ) 

: PINIT 255 UPCRT 2+ C! O UPCRT C! ; 

Next we need a word to send characters to the user 
port and strobe bit 8 of the port: 

( ) ( Strobes bit 8 of user port ) 

: STRC8E8 UPCRT 128 TOGGLE UPCRT 128 TOGGLE ; 

( nl — ) ( Send char to user port ) 
: PCRTOUT 127 AND UPCRT C! STROBE8 ; 

Now vie have a routine to send characters to the USER 
port, all we have to do is vector EMIT to the new 
character output word. 

: TO.UPCRT ' PCRTOUT CFA I/O 2+ ! ; 

The routine above takes the CFA (code field address) 
of the new driver word, and stores it into the third 
and fourth bytes of the I/O vector table in user 
memory. The instant this has been done, any further 
character output will be going to the new driver 
routine. If it doesn't work, then the program may 
hang. To restore the I/O vectors to their initial 
values hit RUN/STOP & RESTORE or type VRESET. Either 
of these will restore all of the VECTORS to their 
initial values. 

NOTE: The example above was to show how to revector 
(C) 1982 Human Engineered Software 35 



EMIT. It was not an example of a complete printer 
driver, since most printers require handshaking that 
I did not include. You will have to study the data 
sheets on the 6522 chip for a while before 
attempting such a driver. 

Vector Word Glossary 



VECTOR, (nl t ; ) This is a new defining word, 

used to add additional words to VICFCRTH that are to 
be vectored. It is used as follows: 

30 <sp> VECTOR <vector name> 

After the above is executed, any time <vector name> 
is executed, it will execute the routine whose CFA 
is in I/O + 30. You must therefore store the CFA of 
a valid dictionary word into it before executing 
<vector name>. 

Note: User VECTORS are from 30 to 50 decimal. 

VW3RDS ( — al ) This word returns the address 
al of the beginning of the initial value vector 
table in RCM. This data may be accessed in the same 
manner as the I/O table to obtain the actual 
routine's CFA for a given vectored word. 

I/O ( al ) This word returns the address 

al of the beginning of the user vector table in RAVI. 
This table is used to change the function of 
selected dictionary words. 

VRESET ( — ) This word when executed 
RESETS all of the vectored dictionary words to their 
initial values, by moving the data at WORDS to the 

36 (C) 1982 Human Engineered Software 



RAM table at I/O. 

6.0 ERRORS, CRASHES AND OTHER PROBLEMS 

6.1 ERROR MESSAGES 

VICFORTH is an 8K byte program. In an effort to 
include as many user features as possible, we have 
had to omit lengthy error messages. Here then is a 
list of the error numbers, and the error messages to 
go with them. 

ERROR MESSAGE 



ERRCRl 




DEC 


HEX 








1 


1 


2 


2 



VICFCRTH DCESN'T KNCW THIS WORD. 

THE DATA STACK IS ALREADY FJVPTY. 

CUT OF USER M3VDRY. 

8 8 SCREEN BLOCK RANGE ERROR. 
You asked for an invalid screenL. 

17 11 USE WHILE COMPILING ONLY. 
This word can't be used while executing. 

18 12 USE DURING EXECUTION ONLY. 
This word can't be used while compiling. 

19 13 CONDITIONALS NOT PAIRED. 
Match your IF - ELSE -ENDIFs. .etc. 

20 14 THIS DEFINITION IS NOT FINISHED. 
You started a conditional without completing it. IE: 
BEGIN missing UNTIL. 

(C) 1982 Human Engineered Software 37 



21 15 THIS WSD IN A PROTECTED 
DICTIONARY. 

You can't forget anything below FENCE. 

22 16 USE ONLY WHEN LOADING. 

23 17 EDIT POINTER IS OFF CURRENT EDIT 
SCREEN. 

24 18 DECLARE YOUR VOCABULARY. 
Specify the VOCABULARY on which you wish to perform 
the operation in, IE: FORTH or EDITOR. 

The VIC-20 KERNEL has several I/O errors that can 
occur, these will be printed out as follows. 

I/O ERROR 15 

The above example indicates an attempt to talk to a 
device which is not in the system, like a disk, or 
printer, here is a full list of the errors that can 
be printed by the KERNEL. These message numbers are 
always printed in DECIMAL. 

I /O ERROR L COMMENT 

ROUTINE TERMINATED BY STOP KEY. 

1 TOO MANY OPEN FILES. 

2 FILE ALREADY OPEN. 

3 FILE NOT OPEN. 

4 FILE NOT FOUND. 

5 DEVICE NOT PRESENT. 

6 FILE IS NOT AN INPUT FILE. 

7 FILE IS NOT AN OUTPUT FILE. 

8 FILE NAVE IS MISSING. 

9 ILLEGAL DEVICE NUVBER. 

6 . 2 WHAT DO I DO WHEN IT CRASHES? 



38 (C) 1982 Human Engineered Software 



VICFCRTH provides a much more powerful programming 
environment than BASIC. Unfortunately it also places 

a higher level of responsibility on you, the 
programmer, than BASIC. There are many ways to 
cause FORTH to 00 AWAY! When this happens, there are 
several ways to recover. If the crash is relatively 
minor, you can press RUN/STCP RESTORE, and FORTH 
will sign back on as if nothing has happened. There 
are however some cases when this will not work. If 
this happens, turn off the power, and then turn it 
back on after a few seconds, and VICFCRTH will 
restart. It is advisable to save any large program 
to cassette tape prior to attempting to execute it. 
This may save you a lot of time later. 

6.3 MESSAGE 

Message is vectored in VICFCRTH, so although full 
length error messages are not built into the system, 
one can add full length error messages by 
revectoring MESSAGE to a user written procedure. 
Type the following lines into screen 1, but don't 
type in the line numbers. 

DECIMAL (NEW MESSAGE ROUTINE) 

1 : NEW MESSAGE GR CLALL ( Nl --- ) 

2 DUP = IF ." WHAT?" ENDIF 

3 DUP 1 = IF ." STACK EMPTY!" ENDIF 

4 DUP 2 = IF ." MEMORY SPACE EXHAUSTED" ENDIF 

5 DUP 8 = IF ." BLOCK RANGE ERROR" ENDIF 

6 DUP 17 = IF ." FOR COMPILING ONLY" ENDIF 

7 DUP 18 = IF ." FOR EXECUTING ONLY" ENDIF 

8 DUP 19 = IF ." IMPROPER CONDITIONALS" ENDIF 

9 DUP 20 = IF .» INCOMPLETE DEFINITION" ENDIF 

10 DUP 21 = IF ." THIS WORD PROTECTED" ENDIF 

11 DUP 22 = IF ." USE ONLY WHEN LOADING" ENDIF 



(C) 1982 Human Engineered Software 39 



12 DIP 23 = IF ." CURSOR OFF SCREEN" ENDIF 

13 DUP 24 = IF ." SPECIFY THE VOCABULARY" ENDIF 
1* SP! QUIT ; 

15 : FULL ' NEW.MESSAGE CFA I/O 18 + ! ; FULL 
DECIMAL ;S 

The above def init ion wi 1 1 now be inserted into the 
VECTOR for IVESSAGE, as shown in line 15 above. To 
reinstate the messages after any warm start type: 
FULL <return>. 

6A FORTH- 79 DIFFERENCES 

VICFCRTH is a fig-FCRTH implementation of the FORTH 
language. The differences between VICFCRTH and 
FCRTH-79 will be covered here on a chapter by 
chapter basis of "STARTING FORTH" to help you 
understand and adjust to the difference. 
STARTING FORTH corrments 

Pg. 12,13 Change the definition of MARGIN to: 

: MARGIN CR 5 SPACES ; 

The VIC-20 has a narrow screen. The above change 
will improve the appearance of the demo. 

Pg. 60 The screens in VICFORTH are numbered 1 
to 6. An unexpanded VIC-20 has screens 1 and 2. 

Pg. 68 Remember that lines in VICFCRTH longer 
than 22 characters will wrap around. VICFCRTH still 
has 64 character lines internally. 

Pg. 76 FLUSH This word is not needed in this 
cassette-based system. 



^0 (C) 1982 Human Engineered Software 



Pg. 77 5 The editor 'S' command is not 

included, due to space restriction. Use the 'F' 
(find) conraand. In VICFCRTH the 'S' corrmand is used 
for Spread a line, which makes room at the current 
edit line for additional text to be inserted. 

Pg. 83 Here is the VICFCRTH definition for a 
stack print uti 1 ity: 

HEX 

60 VARIABLE SO 
: DEPTH SP@ SO @ SWAP - 2 / ; 
: .S 7STACK CR DEPTH 

IF SP@ 2 - SO @ 2 - 
DO I @ 5 .R - 2 
+LCCP 
ELSE ." ENPTY " ENDIF ; 

Pg. 91 0> This operator not supported, use ' 
> ' . (leave a space ) 

p g- 101 ?DUP Not supported use -DIP. 
ABCRT" not supported, use: 

IF ." ERROR MESSAGE " SP! QUIT ENDIF 

Pg. 107 1- 2- 2* 2/ Not supported, use: 
1- 2- 2 * 2/ (leave a space) 

Pg. 110 I* and J are not supported, here are 
their definitions: 

: I ' R> R> R SWAP >R SWAP >R ; 

: 3 R> R> R> R SWAP >R SWAP >R SWAP >R ; 

Pg. 143 PAGE Not supported, here is the 
def ini tion: 

(C) 1982 Human Engineered Software 41 



DECIMAL : PAGE 1*7 EMIT ; 

U.R Not supported, here is the definition: 
: U.R SWAP D.R ; 

Pg. 153 2* and 2/ not supported. Use 2 * and 2 
/. 

Pg. 161 /LOOP Not supported in VICFCRTH. 

Pg. 16* DOUBLE NUVBER DELIMITERS. VICFCRTH 
only recognizes the decimal point "." as a double 
number delimiter. 

Pg. 173 Only D+, D.R supported, for DNEGATE use 
DMINUS. 

PG. 17* Only M* and M/ supplied, but use the 
definitions in the fig-FCRTH instal lat ion manual for 
these words. 

Pg. 183 VARIABLE The definition of 
VARIABLE used in VICFCRTH is the fig-FCRTH 
definition, which requires an initial value to be on 
the stack before creating the variable. 
EXAVPLE: 

12 VARIABLE DATE 

This will create a variable with an initial value of 
12. 

Pg. 193 2VARIABLE, 2CONSTANT, 20, and 2! are 
not supplied in VICFCRTH. See 79-STANDARD 
conversion. 

Pg. 207 CREATE This word functions 

*2 (C) 1982 Human Engineered Software 



differently in VICFCRTH/f ig-FCRTH than in this book, 
use the following to create the definition of LIMITS 
as shown in the book. 

220 VARIABLE LIMITS 340 , 170 , 100 , 190 , 

NOTE: The rule of thumb is to use VARIABLE in 
place of CREATE for definitions which DCNOT have 
DCES> in them. If the definition is of the form: 

CREATE xxxx DCES> xxxx 
then use: <BUILDS xxxx DCES> xxxx 

This conforms to the f ig-FCRTH usage. 

Pg. 216 FIND and EXECUTE VICFCRTH uses the 
f ig-FCRTH word -FIND in place of FIND. In 
f ig-FCRTH the word EXECUTE must receive the code 
field address (CFA) instead of the parameter field 
address (PFA) . Change the example on this page as 
fol lows: 

' GREET CFA EXECUTE <return> 

FCRTH responds with: 

HELLO I SPEAK FCRTH CK 

Pg. 217 VECTCRED EXECUTION The techniques 
will work on VICFCRTH with the modification that the 
addresses obtained with '(tick) are converted to 
code field addresses (CFA) by the use of CFA. 
Example, line 6 would read: 
' HELLO CFA 'ALOHA ! 

SAY The definition of SAY in VICFCRTH is: 

(C) 1982 Human Engineered Software 43 



:SAY [COMPILE] ' CFA 'ALOHA ! ; 

There are two changes here. The word ' (tick) is 
used, and because in fig-FCRTH it is IMVEDIATE, it 
must be compiled by the [COMPILE] word. The second 
change is the use of CFA to prepare the address for 
EXECUTE. 

Pg. 219 NUVBER This definition is vectored 
in VICFCRTH but to revector NUVBER as shown on this 
page, in VICFCRTH you must say: 

DECIMAL ' (number) I/O 10 + ! 

VICFCRTH uses a table, where each entry in the 
table does not have to have a header. Again due to 
space restrictions. 

[ ' ] This word is not supported in VICFCRTH. 
Functionally it is the same as ' (tick). 

Pg. 220 NAVE LENGTHS VICFCRTH supports full 
names up to 31 characters in length. 

Pg. 230 EXIT In VICFCRTH use ;S. 

is not needed, all code is in 



In VICFCRTH use DP. 

In VICFCRTH use SP@. 

Not needed in VICFCRTH. 

N in VICFCRTH. 
CFFSET Not needed in this cassette 

44 (C) 1982 Human Engineered Software 



Pg- 


232 


RELOAD 


RCM 






Pg- 


233, 


237 H 


Pg- 


235 


•s 


Pg- 


239 


OPERATOR 


Pg- 


240 


>IN Us« 



VICFCRTH. 

Pg. 243 ASSEMBLER The assembler may be loaded 
from cassette, if required. 

Pg. 245 LOCATE Not supported in VICFCRTH. 

Pg. 255-257 UPDATE, FLUSH, SAVE-BUFFERS , 

EM'TY-BUFFER, BUFFER These words are not in 
VICFCRTH since it is cassette based. 

Pg. 259 LABEL In VICFCRTH, must change to: 

: LABEL 8 * » "LABEL" 3 + + 8 TYPE SPACE ; 

VICFCRTH does not support ['] and the word ' (tick) 
serves the same function in a definition. 

Pg. 261 >TYPE Not needed in VICFCRTH, use 
TYPE. 

Pg. 266 M3VE, <QO/E Not in VICFCRTH. 

Pg. 272 H Use DP. 

Pg. 281 -TEXT In VICFCRTH use (MATCH) , see 
fig-FCRTH instal lation manual for its definition. 

Pg. 291 VARIABLE, CREATE To create the STARTING 
FORTH type of definition for VARIABLE, use: 

: VARIABLE <BUILDS 2 ALLOT DC£S> ; 

To create the VICFCRTH/ f ig-FCRTH definition for 
VARIABLE, you do it this way: 

: VARIABLE <BUILDS , DCES> ; 

(C) 1982 Human Engineered Software 45 



The f ig-FCRTH word CREATE is used only for creating 
OODE word headers. 

Pg. 292 DEFINING MACROS The definition of a 
DEFINING-W3RD in the book must be changed to: 

: DEFINING-VtCRD <BUILDS (compi le-t ime action) 
DCES> (run-time action) ; 

The EXAMPLE for CONSTANT is then: 

: CONSTANT <BUILDS , DCES> @ ; 

PG. 297 ARRAY The definition of ARRAY must be 
changed to: 

: ARRAY <BUILDS OVER , * ALLOT 

DCES> DIP @ ROT * + + 2+ ; 

Pg. 313 DCES> For most purposes VICFCRTH 
is the same as FORTH-79, but for the advanced 
programmer , see the document FORTH-79 STANDARD 
CONVERSION from the FORTH INTEREST GROUP. 

Pg. 332 JOB, 1FIELD, 2FIELD These must change to 
account for the different CREATE, use: 

20 VARIABLE JCB 2* , 
00 VARIABLE 1FIELD 30 , 
30 VARIABLE 2FIELD 12 , 

Pg. 339 SIMPLE FILES In screen 240 change the 
definitions as follows: 

00 VARIABLE SURNAME. 16 , 
16 VARIABLE GIVEN 12 , 



46 (C) 1982 Human Engineered Software 



28 VARIABLE JOB 24 , 
52 VARIABLE PHONE 12 , 

FREE Change the definition of FREE to the 
fol lowing: 

: FREE 1 MAXRECS 

DO I LRECCRD ! REOORD C0 33 < 
IF 0= LEAVE END IF 
LOOP 
IF ." FILE FULL " QUIT ENDIF ; 

Pg. 339 ' (tick) Prefix all occurances of ' 
with the word [COVPILE], EXAVPLE: 

: CHANGE [COVPILE] ' PUT ; 

Pg. 347 DENSITY, THETA, STRING Prefix ail 
of the words when defined with a zero (0). 
7.0 VICFCRTH AND DISK 

The VICFCRTH system as supplied to you is 
specifically designed to work with cassette, but 
since some people are likely to want to use the 
VIC-20 with the 1540 disk drives, here are some 
routines that will allow you to save programs on the 
disk drive. 

DECIMAL, (select the decimal number base) 

(select the CASSETTE for further operation) 
: CASSETTE SETNAM 1 DL ! 1 FL ! ; 

(Select the DISK for further operation) 
: DISK SETNAM 8 DL ! 15 FL ! ; 

(Write screen nl to the name following 

(C) 1982 Human Engineered Software 47 



NflRITE) 

(nl — t ;) 
: NWRITE NAVE WRITE ; 

(Read screen nl with name following NREAD) 
(nl — t ;) 
: NREAD NAVE READ ; 

Usage of these routines is very sinple. Enter them 
into a screen and save them on cassette for later 
use. When you wish to load or save screens to disk, 
load in these routines from cassette, put a 
formatted disk into the 1540 disk drive. 

Load a created file from cassette, or create a file 
you wish to send to disk, then perform the 
fol lowing; 

DISK <return> 

This selects all READ and WRITE operations to go to 
the DISK. 

1 <sp> MXRITE <sp> TEST1 <return> 

The above corrmand will write screen 1 to disk with 
the name TEST1. All files on disk must have names, 
although they can have numbers for names. 

When you wish to read TEST1 back into a screen enter 
the following corrmand line. 

2 <sp> NREAD <sp> TEST1 <return> 

TEST1 will be read into screen 2. To rewrite TEST1 
back to the same filename, you must prefix the name 
with the "@" sign as follows: 

48 (C) 1982 Human Engineered Software 



2 <sp> MXRITE <sp> 0TEST1 <return> 

Screen 2 will be written back to disk, overwriting 
the original contents of file TEST1. 

To reselect the cassette for further I/O operations 
execute the following command; 

CASSETTE <return> 

The cassette device will be reselected, and the 
filename will be reset to NO-NAVE as is normal for 
cassette block I/O. 

A disk to be used with VICFORTH can be initialized 
using the normal built in BASIC technique. 

NAVE HANDLING GLOSSARY 

FN ( — al ) A user variable which returns a 
pointer to the beginning of a 64 byte buffer, used 
to hold the current FILENAVE. 

SETNAM (al/nl - — ) See SYSTEM CALLS section 2.3. 

NAVE ( --- t ; ) Selects the text following NAVE 
up to a delimiting up arrow or a <return> as the 
current FILENAVE for any READ or WRITE operation on 
CASSETTE, or DISK. The sequence- 

SETNAM <return> 

will reset the current FILENAVE to no name. 

8.0 USEFUL UTILITIES 



(C) 1982 Human Engineered Software 49 



Here is the source for several useful definitions 
you might need in experiment ing wi th your VIC-20. 
These are NOT in VICFCRTH, but may be entered into 
an edit screen and saved to CASSETTE or disk. 

HEX ( dl ) ( returns a double number time) 

: 7TIME FFDE SYS >R 100 * + R> ; 

DECIMAL ( xl/yl x2/y2 ) ( scales to screen 

coord ) 

: SCALE 23 - 4 / SWAP 32 - * / SWAP; 

HEX ( xl/yl ) ( move cursor to x,y ) 

: XY SWAP 2SWAP FFF0 SYS 2DROP 2DRCF ; 

HEX ( — al ) 

( Returns the base address al of the VIC I/O ) 
: ICBASE FFF3 SYS ROT DROP 100 * + ; 

( — ) (Load the current edit screen) 
: TRY SCR @ LOAD ; 

( nl) (Return the amount of free memory) 

: FREE EM @ HERE - ; 

(nl ) (Close file number nl) 

: CLOSE FFC3 SYS 3DROP ; 

( dl/d2 -— dl/d2/dl ) 

( Duplicate the double number dl over top of ) 
( double number d2. ) 
:20VER >R >R 2DUP R> R> 2SWAP ; 

DECIMAL (Select the decimal number base.) 
( — fl ) 

50 (C) 1982 Human Engineered Software 



( Read the joystick and return a boolean flag. ) 

30 37137 03 4 AND 0= 

31 37137 C@ 8 AND 0= 

32 37137 C@ 16 AND 0= 

33 37154 128 TOGGLE 37152 G0 128 AND 0= 
37154 128 TOGGLE ; 

: FIRE 37137 C@ 32 AND 0= ; 

( — x/y ) 

( Read the analog paddles, and return x and y. ) 
: PADDLEXY 36872 @ 256 A/DD ; 

( — ) 

( Toggle the auto repeat switch in the system. ) 
( Causes all keys to repeat when held down. ) 
( WARNING: May also cause some keybounce. ) 
: AUTO. REPEAT 650 128 TOGGLE ; 

HEX 

(— nl) 

( Read the system status byte, see the ) 

( PROGRAMVERS REFERENCE MANUAL. ) 
: STATUS FFB7 SYS 2DRCP ; 

HEX 

( Turn on RS-232 port at 300 baud ) 

( Use CLALL to restore OUTPUT to SCREEN ) 

: SERIAL.ON 6 293 C! 294 C! ( Set baud and parity 

293 2 SETNAM ( Tell them to the system ) 

2 2 SETFLS ( Set the logical file ) 

CPEN ( Open the channel to RS-232 ) 

2 CHKOUT ; ( Direct output to the channel) 

DECIMAL ( Select the Decimal number base. ) 

( Generate a short tone ) 
: BEEP 10 VCLUVE ( Set the volume of the tone ) 

(C) 1982 Human Engineered Software 51 



293 TENOR C! ( Turn on the TENCR voice = 

293) 

1000 DO LOO? ( Wait a short time ) 

TENCR C! ; ( Turn off the TENCR voice=0 ) 

9 . V ICFCRTH ALPHABET I ZED GLOSSARY 

You can obtain a complete glossary of all fig-FCRTH 
words by requesting it from the FORTH INTEREST 
GROUP, whose address is given in Section 1.6. Below 
is a glossary of VICFCRTH words that do not appear 
in the fig glossary. 

tBLCCKS ( nl — ) 

Clears out memory, and sets the number of screen 
buffers to value nl, after clipping nl to within the 
limits (1) and the max memory wi 11 allow minus 1. 

(M^TCH) ( addrl/addr2/nl — fl ) 

Compare the strings at addrl and addr2 for length nl 
for equality. Return boolean flag fl true for 
match, and false for no-match. 



2DRO? ( dl — ) 

Drop the double number from the top of the stack. 

2DUP ( dl -— dl/dl ) 

Copy the double number on the top of the stack. The 

duplicate becomes the new top of stack. 

2SWAP ( dl/d2 — d2/dl ) 

The position of the two double numbers on top of the 

stack is swapped. 

3DRO? ( nl/n2/n3 --- ) 

Drop the three 16 bit values from the stack, used in 

system calls to clean off the stack. 

52 (C) 1982 Human Engineered Software 



<= ( nl/n2 --- f ) 

Leave a true flag if nl is less than or equal to n2. 

Otherwise, a false flag is left. 



ALTO ( --- addrl ) 

Return the address of the alto voice in the VIC 

chip. Values between 128 and 255 turn this voice 

on. 

ASCII ( --- nl ) P 

Smart word, compiles char following into dictionary 
as a literal if in compile state, else places its 
value on the stack. 



BOROUND ( nl --- ) 

Select value nl as the current BackGRCUND color. 

BM\X ( -— addrl ) S 
A system variable containing the highest value BLK 
is allowed to assume. If BLK is greater than BM\X, 
an appropriate error message is issued. 

BORDER ( nl — ) 

Select value nl as the current BORDER color. 

CrKCUT ( nl — ) 

Set file number nl as the current terminal output 

device for all character output. See PRON, and 

PRINT. The file number nl must have been previously 

opened. 

CLALL ( --- ) 

System call to CLear-ALL I/O devices to the default 

values. See the Programmers Reference Guide. 



(C) 1982 Human Engineered Software 53 



Dt ( --- addrl ) 

A user variable which holds the current READ/WITE 

device number, defaults to 1 for cassette. 



EDIT ( nl — ) 

Select the screen nl for editing, select the EDITCR 
vocabulary, and go into the split screen mode. 
Enables the captured keys for cursor control. 

EM ( --- addrl ) 

A system variable, holds the end of memory pointer. 

EMIT ( b — ) 

Transmit byte, b, to the selected output device. 

CUT is incremented for each character output. The 

output device is determined by the channel number 

contained in CUTCH, and what file is opened on that 

channel. 

Ft ( — addrl ) 

A user variable which holds the current file number 
for all READ/V&RITE operations. Defaults to 1 for 
cassette operation. 

FN ( — addrl ) 

A user variable which holds the name of the current 

READ/VSRITE file. This buffer is 64 characters long. 



H. ( nl — ) 

Print the value nl from the stack to the current 

output device, as an unsigned hexadecimal number. 

I/O ( — addrl ) 



54 (C) 1982 Human Engineered Software 



A user variable which returns the beginning address 
of the I/O vector table area. See 5.2 for the 
positions of each of the vectored words in the 
table. 



NAVE ( --- ) 

Accept the text following NAVE until a delimiting 
up-arrow character or a <return> is entered. Place 
the text into user array FN, with the count byte in 
the first char of FN. 

NOISE ( — addrl ) 

A system constant which returns the address of the 
NOISE voice of the VIC chip; values between 128 and 
255 turn the voice on. 

OPEN ( — ) 

A system corrmand which opens the filename, file 
number, and device just specified in the last SETFLS 
and SETNAV1 commands. 

PRINT ( — ) 

Print any output from the line of commands following 

the print corrmand to the serial bus printer, device 

U. 

PRDN ( --- ) 

Send all terminal output to the serial bus printer, 

device number k. Can be restored by CLALL. 

READ ( nl — ) 

Read the first screen from the current device as 
specified by DL and Ft, into screen nl. Normally 
will read from cassette, but can be made to read 
from disk, by changing DL, Ft, and specifying a name 
for the file. Will read named files from cassette, 

(C) 1982 Human Engineered Software 55 



by specifying a name for the cassette file. 

READS ( nl/n2 -— ) 

Read from cassette to screen nl through nl+n2. The 
value n2 is the quantity of screens to read. This 
word can not be made to read screens from disk, 
since each disk screen must have a different name. 

SAVE ( addrl/nl -— ) 

Save the data or program from address addrl for a 

count of nl bytes to the currently open mass storage 

device. 

SETFLS ( nl/n2/n3 — ) 

Set the logical file with filenimber nl, device 
number n2, and secondary corrmand n3 into the 
operating system. 

SETNAV1 ( addrl/nl --- ) 

Set the string at address addrl for count nl as the 

name of the current mass storage file name. 

SYS ( <fl>/nl/n2/n3/addrl -— <f l>/n*/n5/n6 ) 
Perform a system call to an assembly language 
routine, at address addrl, with the cpu registers 
A,X,Y as values nl,n2,n3. Pass optional flag <fl> 
as the carry state. Return n4,n5,n6 as the cpu 
registers A,X,Y and return <fl> unmodified. 

SL£AD ( addrl -— ) 

Load the program from the current device, into 
address addrl. The length of the load is determined 
by the file being loaded. 

SCPRANO ( — addrl ) 

A system constant , which returns the address of the 

SCPRANO voice in the VIC chip. Values between 128 

56 (C) 1982 Human Engineered Software 



and 255 turn this voice on. 

TENOR ( — addrl ) 

A system constant which returns the address of the 
TENCR voice in the VIC chip. Values between 128 and 
255 turn this voice on. 

THRU ( nl/n2 — ) 

Load screens nl through screen n2, from the screen 
buffers already in memory. DCES-NOT read any 
screens from cassette. 

U< ( nl/n2 — fl ) 

Perform an unsigned less than comparison on nl and 

n2. Return boolean flag fl true if nl is less than 

n2. 

U. ( ul — ) 

Print the number ul to the currently selected output 

device, as an unsigned number in the current base. 

UPORT ( — addrl ) 

A system constant, returns the address of the USER 

port. 

VECTCR ( nl -— ) 

A defining word used in the form: 

nl VECTCR nnnn 
To create a word 'nnnn' which when executed will 
itself execute the contents of the nl vectored 
routine in the I/O table. User created vectored 
words must start at value 30 decimal and must not be 
higher than 50. 

VQLUVE ( nl — ) 

Values between and 15 decimal control the VOLUVE 

of all the voices in the VIC chip. 

(C) 1982 Human Engineered Software 57 



VRESET ( — ) 

Reset all I/O vectors to their default values as 
held in the default table VAXCRDS . The values of Ft 
and Dt are also reset to 1. 

WtCRDS ( — addrl ) 

This word returns the address addrl of the beginning 
of the initial value vector table in RCM. See 
section 5.2 for the positions of the vectored words 
in the table. 

WRITE ( nl --- ) 

Write screen nl to the current device, as specified 
by Dt and Ft. The written screen will be sent to 
cassette unless Dt and Ft are set for disk. 

WRITES ( nl/n2 --- ) 

Screens nl through nl+n2 will be written to 

cassette. Can not be made to write to disk. 



58 (C) 1982 Human Engineered Software 



flg-FORTH GLOSSARY 



This glomry contains all of the word def- 
initions In Release 1 of flg-FORTH. The 
definitions are presented In the order of 
their ascll sort* 

The first line of each entry shows a symbolic 
description of the action of the proceedure on 
the parameter stack. The symbols lndlcste the 
order In which Input parameters have been 

placed on the stack. Three dashes " " 

Indicate the execution point; any parameters 
left on the stack are listed. In this 
notation, the top of the stack la to the 
r lch t • 

The symbols Include: 



addr 
b 



f 

f f 



tf 



memory address 

8 bit byte (i.e. hi 8 bits sero) 

7 bit ascll character (hi 9 bits aero) 

32 bit sinned double Integer, 

most significant portion with sign 

on top of stack, 
boolean flag. O-false, non-«ero-t rue 
boolean false flag-0 
16 bit signed Integer number 
16 bit unsigned Integer 
boolean true f iag-non-sero 



The capital lettera on the right show defin- 
ition characteristics: 

C May only be used within a colon defin- 
ition. A digit Indicates number 
of memory addreases used. If other 
than one. 

E Intended for execution only. 

LO Level Zero definition of FORTH-78 

LI Level One definition of FORTH-78 



U 



Has precedence bit set. Will execute 

even when compiling. 
A user variable. 



Unless otherwise noted, all references to 
numbers are for 16 bit signed Integers. On 
8 bit data bus computers, the high byte of 
a number la on top of the stack, with the sign 
in the leftmost bit. For 32 bit signed double 
numbers, the moat significant part (with the 
sign) Is on top. 

All arithemetlc la Implicitly 16 bit signed 
integer math, with error and under-flow 
indication unspecified. 



n addr 

Store 16 bits of tj 
Pronounced "store" 



at address. 



Save the stack position in C S P . Used 
as part of the compiler ^security. 

dl d2 LO 

Generate from a double number dl, the 
next ascll character which is placed 
in an output string. Result d2 is 
the quotient after division by BASE, 
and Is maintained for further pro- 
ceasing. Used between <# and #>. 
See #S. 



d addr count LO 

Terminates numeric output conversion 
by dropping d, leaving the text 
address and character count suitable 
for TYPE. 



FORTH INTEREST GROUP RO. Box 1105 San Carlos, Ca. 94070 



Used in the form: 
nnnn 



DO which moves the loop control para 
meters to the return stack. See DO. 



IS dl d2 LO (+LOOP) n C2 

Cenerates ascii text in the text out- The run-time proceedure cosplled 

put buffer, by the use of t, until b y +LOOP, which i nc r eme n t o the loop 

a zero double number n2 results. index by n and tests for loop comple- 

Used between <# and #>. tion. See +LO0P. 

,a*t P in (ABORT) 

a °_ r,LU Executes after an error when WARNING 

le -1. This word normally executes 
ABORT, but may be altered (with care) 

Leaves the parameter field address t0 a user's alternative proceedure. 

of dictionary word nnnn. As a coup- - 

Her directive, executes in « colon- (DO) 

j *i j^j .. j, *i_ jj The run-time proceedure compiled by 

definition to compile the address „_ . . ... \ , _,1 

as a literal. If the word is not 
found after a search of CONTEXT and 

CURRENT, an appropriate error mess- (FIND) addrl addr2 pfa b tf (ok) 

age is given. Pronounced "tick". addrl addr2 ff (bad) 

Searches the dictionary starting at 

( P,LO the name field address addr2, match- 
Used in the torn: i ng to the text at addrl. Returns 

( cccc) parameter field address, length 

Ignore s comment that will be byte of name field and boolean true 

delimited by a right parenthesis f or a good match. If no match is 

on the same line. May occur during found, only a boolean false is left, 
execution or in a colon-definition. 

A blank after the leading parenthesis (LINE) nl n2 --- addr count 

is required. Convert the line number nl and the 

„ screen n2 to the disc buffer address 

(• ' c+ containing the data. A count of 64 

The run-time proceedure, compiled by indicates the full line text length. 
." which transmits the following 

in-line text to the selected output (LOOP) c2 

device. See ." The tu;i-ti«e proceedure compiled by 

f-rnn^ • LOOP which increments the loop index 

(, CODE) c and tests for loop completion. 

The run-time proceedure, compiled by See T.00P. 
[CODE, that rewrites the code field 

of the most recently defined word to (NUMBER) dl addrl d2 addr2 

point to the following machine code Convert the ascii text beginning at 

sequence. See ;CODE. addrl+1 with regard to BASE. The new 

value is accumulated into double 
number dl, being left as d2. Addr2 

FORTH INTEREST GROUP RO. Box 1105 San Carlos, Ca. 94070 



'/MOD 



is the address of the first uncon- 
vertible digit. Used by NUMBER. 

al n2 prod LO 

Leave the signed product of two 
signed numbers* 

nl n2 n3 n4 LO 

Leave the ratio n4 • nl*n2/n3 
where all are signed numbers. Ret- 
ention of an int ermedia t e 31 bit 
product permits greater accuracy than 
would be available with the sequence: 
nl n2 * n3 / 

nl n2 n3 n* n5 LO 

Leave the quotient n5 and remainder 
n4 of the operation nl*n2/n3 
A 31 bit intermediate product is 
usad as for */. 

n 1 n 2 sum ^ 

Leave the sum of nl+n2. 

n addr LO 

Add n to the value at the address. 
Pronounced "plus-itore". 

nl n2 n3 

Apply the sign of n2 to nl, which 
Is left as n 3 . 

addl addr2 f 

Advance the disc buffer address addrl 
to the address of the next buffer 
addr2. Boolean f is fal&e when addr2 
Is the buffer presently pointed to 
by variable PREV. 

nl (run) 

n2 (c omp lie; 

colon-definition in 



addr 
Used In a 
form: 

DO 
At run-t 1 



P,C2 ,L0 
the 



nl 
+ LOOP 



+LOOP 
se lee t i ve ly 



fOKICIN 



controls branching back to the cor- 
responding DO based on nl, the loop 
index and the loop limit. The signed 
increment nl Is added to the index 
and the total compared to the limit. 
The branch back to DO occurs until 
the new index is equal to or greater 
than the limit (nl>0), or until the 
new index is equal to or less than 
the limit (nl<0). Upon exiting the 
loop, the parameters are discarded 
and execution continues ahead. 

At compile time, +L0OP compiles 
the run-time word (+L0OP) and the 
branch offset computed from HERE to 
the address left on the stack by 
DO. n2 is used for compile time 
error checking. 

n addr 

Leave the aemory address relative 
by n to the origin parameter area. 
n is the minimum address unit, either 
byte or word. This definition is , used 
to access or modify the boot-up 
parameters at the origin area. 

n LO 

Store n into the next available dict- 
ionary memory cell, advancing the 
dictionary pointer. (comma) 

nl r 
Leave thi 



2 dlff 

difference of 



LO 



nl-n2. 



Continue interpretation with tha 
next disc screen, (pronounced 
next-screen) . 



P,L0 



FORTH INTEREST GROUP R 0. Box 1105 



San Carlos, Ca. 94070 



nl " nl < lf ""I characters nay be an installation 

nl -- nl nl (non-iero) LO dependent value. See (."). 

Reproduce nl only If it is non-iero. 

This la usually used to copy a value -.LINE line icr --- 

Juat before IF, to eliminate the need Print on the terminal device, a line 

for an ELSE part to drop It. of text from the disc by its line and 



-FIND pfa b tf (found) 

f f (not found ) 

Accepts the next text word (delimited 



•creen number. Trailing blanks are 
suppressed. 

nl n2 



bv blanks) in the Input strean to Print the number nl right aligned in 

HERE, and searches the CONTEXT and a fl « ld "hose width la n2. No 

then CURRENT vocabularies for a following blank is printed. 

catching entry. If found, the , , , ,„ 

., ,. . , / nl n2 - — quot LO 

dictionary entry s parameter field T u ^ -.-..-*,/•* 

A . ' . ' . r . iiciu Leave the signed Quotient of nl/o2. 
address, its length byte, and a 

boolean true is left. Otherwise, /MOD nl n2 rem quot LO 

only a boolean false la left. Leave the remainder and signed 

-TRAILING addr nl addr n2 quotient of nl/n2. The remainder has 

Adjusts the character count nl of a the ,lgn of the dividend, 

text string beginning address to 1 ? ^ n 

suppress the output of trailing These small numbers are used m often 

blanks. i.e. the characters at th » c ls la attractive to define them 

addr+ol to addr+n2 are blanks. b * n *«" in the dictionary aa const- 
ants, 

o LO 

Print a number from a signed 16 bit 0< r f 

two's complement value, converted Leave a true flag if the number Is 

according to the numeric BASE. le88 thon " r0 (n '8" tiv,) ' otherwise 

A trailing blanks follows. leave a false flag. 

Pronounced "dot". 0- n f LO 

M P,L0 Leave a true flag is the number is 

Used 10 the forn: e 1 ual to fero - otherwise leave a 

." cccc" false fl "«- 



Compiles an in-line string cccc 
(delimited by the trailing ") with an 



BRANCH f C2 

, . The run-time proceedure to condition- 
execution proceedure to transmit the ally t, ranc h. If f is false (zero), 
text to the selected output device. ^ the f ii oulng in-line parameter la 
I£ executed outside a definition, . added to the interpretive pointer to 
will immediately print the text until branch ahead or back. Compiled by 
the final ". The maximum number of Jp UNTILi and WHILE. 

FORTH INTEREST GROUP R 0. Box 1105 San Carlos, Ca. 94070 



1+ nl --- n2 



doaa so by Jumping to the code aftej 



Increment nl by 1. nnnn . An , Kl , tlng aeIlnlng word 

2+ nl n2 autt «il»t in cccc prior to ;CODE. 

Leave nl Incremented by 2. . c pin 

• P.E.LO Stop Interpretation of a ictrrn. 

Uaed in the form called a colon- >S la also the run-time word compiled 

definition: at the end of ace Ion -definition 

: cccc ... ; which returns execution to the 

Creates a dictionary entry defining calling proceedure. 

cccc as equivalent to the following < „j n 2 f L0 

sequence of Forth word definitions Leave a true flag if nl is less than 

until the next ';' or ';C0DE'. n 2 ■ otherwise leave a false flag. 
The compiling process is done by 

the text interpreter as long as *' LO 

STATE is non-zero. Other details Setup for pictured numeric output 

are that the CONTEXT vocabulary is formatting using the words: 

set to the CURRENT vocabulary and <# * ' s SIGN #> 

that words with the precedence bit ~ ne conversion is done on a double 

set (P) are executed rather than number producing text at PAD. 

being compiled. <B01LDS C ,L0 

S P,C,LO Used within a colon-definition: 

Terminate a colon-definition and : cccc <BUILDS ... 

•top further compilation. Compiles DOES> ... ; 

the run-time ;S. Each time cccc is executed, <BUILDS 

iCODE * P,C,L0 defines a new word with a high-level 

Daed in the form: execution proceedure. Executing cccc 

: cccc .... ;CODE in the form: 

assembly mnemonics cccc nnnn 

Stop compilation and terminate a new usee <BUILDS to create a dictionary 

defining word cccc by compiling entry for nnnn with a call to the 

(;CODE). Set the CONTEXT vocabulary DOES> part for nnnn. When nnnn Is 

to ASSEMBER, assembling to machine later executed, it has the address of 

code the following mnemonics. ite parameter area on the stack and 

executes the words after DOES> in 

When cccc later executes in the form: cccc. <BUILDS and D0ES> allow run- 

cccc nnnn time proceedures to written in high- 

the word nnnn will be created with level rather than in asaembler code 

ita execution proceedure given by (a " r ^ ulre,! h y iCODE). 
by tha machine code following cccc. 
That la, vhen nnnn ia executed. It 

FORTH INTEREST GROUP R 0. Box 1105 San Carlos, Ca. 94070 



TCSP 



Dl n2 f LO may be Installation dependent. 

Leave a true flag if nl-n2; other- 



wise leave a false flag. 



7TERNINAL f 

Perform a test of the terminal key- 
> nl n2 f LO board for actuation of the break key. 

Leave a true flag If nl la greater A true flag indicates actuation. 

than n2j othervlse a false flag. Thia definition is installation 

>R „ — C>L0 dependent. 

Remove a number from the computation a addr n LO 

atack and place as the most access- Leave the 16 bit contents of address. 

able on the return stack. Use should 

be balanced with R> in the same ABORT LO 

definition. Clear the stacks and enter the ittc- 

1 ,d<jr in ution state. Return control to the 

„_, . „,. , .. . , operators terminal, printing a aess- 

Print the value contained at the . appropriate to the in. t 111. tion. 

address in free format according to 

the current baae. ABS n u LO 

JCOMP Leave the absolute value of n as u. 

Issue error message if not compiling. ACAIH addr n (compiling) P.C2.L0 

Deed in a colon-def lnlon in the formi 



Issue error message If stack position 



BEGIN ... AGAIN 



differs from value saved In CSP. At run-time, AGAIN forces execution 

to return to corresponding BEGIN. 
TERR&a ' n •" There is no effect on the atack. 

Issue an error message number r, if Execution cannot leave this loop 

the boolean flag i, t ru.. (unless R> DROP is executed on* 

7ZXEC 1 « vtl belov). 

Issue an error message if not mc- 
utiog. At compile time, AGAIN compiles 

BRANCH with an offa.t from HERE to 

Issue an error message if not loading tiir ' n 1 » u " d tor Compil.-time 

error checking. 



7L0ADING 



7PAIRS nl n2 

laaue an error message if nl does not 



ALLOT n LO 

Add the signed number to the diction- 



equal n2. The message indicate, that pointer DP. May be u.ed to 

compiled conditional, do not match. reserve dictionary .pace or re-orl«ln 

7STACK memory. n i. with regard to computer 

laaue an error mesaage is the stack addr... typ. (byt. or word), 

is out of bounda. Thia definition 

FORTH INTEREST GROUP R 0. Box 1105 San Carlos, Ca. 94070 



*■» nl n2 n2 LO 

Leave the bitwise logical and of ol 

and n? m a « ^ 



BL c 

A constant that leaves the tscli 



— ^ __ — A constant cnat i 

and o2 «. n 3. valua for « blnnk » 



B/BC7 ■— n BLAM.S 



addr count 



--— — ~.# « U u* count — -- 

This constant leaves the number of >< , , . 

k»f.. „.,- ,*<.,. >. i t .v. v rill an area of iiiom baglnlng 

byte, per disc buffer, th. byte count « ddr with. blanks. 



rn 



P .. ^.<- nuuer, tna nyte count « ddr with. blanks 

d fro. dlac by BLOCK. 



1/SC1 --- n * ht "~ * ddr D ' L0 

Thl. con.t.nt leaves th. nu.ber of *"" fc!^ JV " Bt * ln i a « "« bloek 

block, per editing acreeo. By con- !„™r ^ J ? lnt " pr " ,d ' I£ " r °- 

v.ntlon, an editing .creen 1. 1024 input 1. being taken fro- the e.r.- 

byte. organired a. 16 Una. of 64 ln,X lnpUt ""««. 

characters each. BLOCK n addr LO 



BACK addr 



Leave the aemory addreaa of the block 



r i i . TZ~ v. i. j v i. buffer containing block n. If the 

Calculate the backward branch offset v , . 4 . .. , , , . 

„ , , block la not already in aenory. It la 

from HERE to addr and compile Into trao.f.rr.d froa dlac to which ever 

the next available dictionary aemory buffer wae le.at recently written. 

«*e» addreaa. I£ th# block occupying that buffer 

BASE — .ddr ,LO h „ b .. n B . rk . d a . up<Utedt lt t. r ._ 

A u.er variable contanlng the current written to dlac before '.lock n la 

number baae used for input and out- r .. d into the buffer. See alio 

put conversion. BUFFER, R/V DPDATE FLDSH 

BECIN -— addr n (compiling) P.LO iL0 CK-»t.AD 

Occur* in a colon-definition In form: ,, nr , ubttf T k . 

BECIN ... UNTIL BLOCK-WRITE These are the preferred name. 

BEGIN ... AGAIN f ° r the u,t,11 «tlon dependent code 

BEGIN ... WHILE ... REPEAT disc?"' * " " "^ ° D ' bl ° CV " th < 

At run-time, BEGIN Barks the atart BRANCH 

of a aequence that Bay be repetitive- Th . .„„ ,,_. „, . C2.L0 

ly executed. It serve, a. a return . " L I I"^ uncondlt- 

polnt froa th. cor re. poinding UNTIL, " / " | /" in-line offset 

AGAIN or REPEAT. When ax.cuting !f *"*' '° th « '"'"'["" pointer 

DNTIL, a return to BEGIN will occur " " b "" \ ' h " t " bBck ' B " ANCH 

if th. top of the stack la f.l.e; '" C °"^ 1 ' i b > ELSE . AGAIN. REPEAT. 

for AGAIN and REPEAT a return to BUFFER n addr 

BECIN alwaya occurs. Obtain the next meaory buffer, aas- 
At coapile time BEGIN leavee its ret- igning it to block n. If the con- 
urn addreaa and n for compiler error tents of the buffer Is marked aa up- 
checking, dated, lt la written to the diac 

The block la not read from the diac. 

FORTH INTEREST GROUP R0. Box 1105 San Carlos, Ca. 94070 



COLD 



The address left Is the first cell remove application prograas and 

within the buffer for data storage. raetart. 

b addr COMPILE C2 

Store 8 bits at address. On word When the word containing COMPILE 

addressing computera, further spec- executes, the execution address of 

ification is necessary regarding byte the word following COMPILE is copied 

addreaslng. (cooplled! Into the dictionary. 



b 



This allows specific compilation 
situations to be handled in addlton 



Store 8 bits of b into the next t£) 8lBply COEp i lng an execution 

available dictionary byte, advancing address (which the Interpreter 

the dictionary pointer. This la only already does). 
available on byte addressing corap- 

utera, and ahould b« used with CONSTANT n LO 

caution on byte addresalng mini- A defining word used in the form: 

computers. n CONSTANT cccc 

to creste word cccc, with its para- 

C£ addr b meter field containing n. When cccc 

Leave the 8 bit- contents of memory ia later executed, it will push 

addreaa. On word addreaaing comput- the vll „ o{ „ to the , llck , 
era, further apec i f ica 1 1 on is needed 

regarding byte addressing. CONTEXT addr U.LO 

A user variable containing a pointer 

C7A pf« cfa t0 tne vocabulary within which diet- 
Convert the parameter field address ionary searches will first begin. 

of a definition to ita code field 

address. COUHT addrl addr2 n LO 

CM.OVE fro. to count — Leave the byte addre.s addr2 and byte 

Move the specified quantity of byte. coun ' n of ' """' 8 ' "" be 8innlng 

. , j * .. c \.„ _jj.._. at address addrl. It is presumed 

beginning at addresa from to address .*. , . 

_. . t jj *.-_ that the first byte et sddrl contains 

to. The contents of addresa froti , , J 

j «. ., , .. ., . the text byte count and the actual 

la moved firat proceeding toward high .,,_■_ . .. 

_ ....1. . <n,..n„» i. text atarts with the second byte. 

memory. Further specification Is Typically COUNT 1, followed by TYPE. 

necesssry on word addressing cosp- " ' 

utera. CR LO 

Transmit a carriage return and line 

The cold atart proceedure to adjust feed to * h « selected output device. 

the dictionary pointer to the ala- CREATE 

lmua standard and reatart via ABORT. A defining word used in the form: 

May be called from the terminal to CREATE cccc 

FORTH INTEREST GROUP R 0. Box 1105 San Carlos, Ca. 94070 



bjr such word. as CODE and CONSTANT CONTEXT vocabulary. In the example 

'V'T! "dictionary he. der for executing vocabulary name cccc „d. 

a Forth definition. The code field , f ,.,,„ „,„„. . , 

It the CONTEXT vocabulary and tuc- 

cont.lns the address of the words utlng DEFINITIONS m.de both specify 

parameter field. The new word Is vocabulary cc-c 
created in the CURRENT vocablary. 

CSP .ddr v D1GIT c nl — n2 tf (ok) 

A user variable temporarily storing r»,„!r,°',i"" V. <- <b<!d) 

the stack pointer position, for 5 onverts the a.cii character c (using 

coiapllatlon error checking. *"' ""Z" * C ' "n"y equivalent n2, 

* accompanied by a true flag. If the 

D+ dl d2 dsum conversion is invalid, leaves only 

Leave the double number sub of two * false fla 8- 

double numbers. DLIST 

D+- dl n d2 List the names of the dictionary 

Apply the sign of n to the double entries in the CONTEXT vocabulary, 
number dl, leaving it as d2. 

D. d L1 eL HERAL d d (executing) 

aoie on tne stack. Conversion Is n.„.i ,n „.. .1. <» .. ..,_ ^ , 



performed according to the current 



literal will puah it to the stack. If 



»*<!* a k ,.„v , ,? ; «."'ien C executing, the number will remain on 

BASK. A blank follows. Pronounced ,k. ■ i-.,.v 

D-dot. 



d 



the stack. 
DMIHDS dl d2 



Print a signed double number d risht Convert dl to its double number two's 

aligned in a field n character, wida. ■„„ complement. 

DABS <j ud D0 nI ° 2 (execute) 

I».v. ,k. v. , * ddr n (cocplle) P,C2',L0 

double number V ' 1U * Ud ° f * ° CCUrL in " colon-definition In form: 

DO ... LOOP 

DEC IMAL L0 DO ... +LOOP 

Set the numeric conversion BASE for At run time, DO begins a sequence 

decimal input-output. with repetitive execution controlled 



DEFINITIONS L1 



by a loop limit nl and an index with 



Heed In the form- Initial velue n2. DO removes these 

cccc DEFINITIONS 'TV^ " tark " Uf> ° n r " chln « L00? 

Set the CURRENT vocabulary to the „*V "f" 1S 1 """ ,t,d , b » ° n '- 

' until the new index equals or exceeds 

FORTH INTEREST GROUP R 0. Box 1105 San Carlos, Ca. 94070 



DOES> 



DP 



DPL 



the limit, execution loops back to 
Juet after DO; otherwise the loop 
parameters are discarded and execut- 
ion continues ahead. Both n I and n2 
are determined at run-time and may be 
the result of other operations. 
Within a loop ' I ' will copy the 

urrent value of the index to the 
BXack. See I, LOOP, +LO0F, LEAVE. 

When compiling within the colon- 
definition, DO compiles (DO), leaves 

*-K«* fi-iTlnuIno a r 1 . A y o a ti a A A r a n <*. n for 



LO 



ed 
he 



the following address addr and 
later error checking. 

A wo rd wh ich defines the run-time 
action within a high-level defining 
word. DOES> altera the code field 
and first parameter of the new word 
to execute the sequence of compiled 
word addreesee following DOES > . Ua 
in combination with <BUILDS. When t 
DOES> part executes it begins with 
the address of the f 1 r b t parameter 
of the new word on the stack. This 
allows interpretation using this 
ares or ite contents. Typical uses 
include the Forth ass emb lei, oulti- 
dimi ns ional arrays, and compiler 
geat r a t ion . 

addr U,l 

A user variable » the dictionary 
pointer, vhich contains the addreBB 
of the next free memory above the 
dictionary. The value aay be read by 
HERE and altered by ALLOT. 

addr U,L0 

A uiar variable containing the number 
of digits to the right of the decimal 
on double integer input. It may also 



DRQ 
DR1 



DROP 
DUMP 



be uaed hold output column location 
of a decimal point, In user generated 
formating. The default value on 
single number Input is - 1 . 

Installation dependent commands to 
select dlac drives, by preaeting 
OFFSET. The contents of OFFSET Is 
added to the block number in BLOCK 
to allow for this aelectlon. Offaet 
is supreased for error text ao that 
Is nay always originate from drive 0. 

n LO 

Drop the number from the stack. 



addr n --- 
Print the contents of n nemory 
locations beginning at addr. Both 
addressee and contents are shown in 
the current numeric base. 



LO 



LO 



Duplicate the value 



the stack. 



addrl nl addr2 n2 

(compiling) P.C2.L0 
Occurs within a colon-d«f ini t ion 
in the foro: 

IF ... ELSE . . . EHDIF 
At run-time, ELSE executes after the 
true part following IP. ELSE forcei 
execution to skip over the following 
false part and resumes execution 
after the ENDIF. It has no stack 
effect. 

At comp lie-time ELSE emplacea BRANCH 
reserving a branch offset, leaves 
the address addr 2 and n2 for error 
testing. ELSE also resolves the 
pending forward branch from IF by 
calculating the offaet from addrl to 
HERE and storing at addrl. 



FORTH INTEREST GROUP P. 0. Box 1105 San Carlos, Ca. 94070 



EMIT c LO 



At coapllt-tloe, ENDIF computes the 



Transmit asr..il character c to the forward branch offaet from addr to 

.elected output device. OUT 1. HE8g „ nd 8tort8 1 1 . t 1<Jdr . „ j, 

incremented for each character utti for error testa, 
output. 

ERASE addr n 

EMPTY-BUFFERS LO Clear a region of memory to zero fro« 



Mark all b lo ck-buf f era ai empty, not addr over n addresses 

necessarily affecting the contents 
Updated blocks are not written to the 



line in blk 



disc. Thie ia al.o an inl t iellte t ion Execute error notification and re- 

proceedure before first u.e of the mtaIt o£ "l"'"' WARNING i. first 

disc, examined. If 1, the text of line n, 

relative to screen & of drive is 

EBCLOSE addrl c printed. This line number may be 

adrl nl n2 n3 poaitive or negative, and beyond Just 

The text scanning primitive uaed by screen 4. If WARNING-0, n is Just 

VORr. From the text address addrl printed as a message number (non disc 

and an ascii delimiting character c, installation). If WARNING 1 ■.. -1, 

is determined the byte offaet to the the definition (ABORT) is executed, 

first non-delimiter character nl, which executee the system ABORT. The 

the offset to the firat delimiter uaer may cautiously modify thia 

after the text c2, and the offset execution by altering (ABORT), 

to the first character not included. flg-FORTB saves the contents of IN 

This proceedure will not process past and BLK to assist in determining the 

an aacll 'null', treating it aa an location of the error. Final action 

unconditional delimiter. lo execution of QUIT. 

E»D r,C2,L0 EXECUTE addr — 

This ia an 'alias' or duplicate Execute the definition whose code 

definition for UHTIL. field address is on the stack. The 



code field address is also called 
the compilation address. 



ENDIF addr n (compile) P , C , L 

Occurs in s c o 1 on -de f lni t ion In form: 

IF ... ENDIF EXPECT addr count LO 

IF ... ELSE ... ENDIF Transfer characters from the terminal 

At run-time, ENDIF servei only as the to address, until a "return" or the 

destination of a forward branch from count of charactera have been rec- 

1F or ELSE. It marka the conclusion elved. One or sort: nulls are added 

of the conditional atructure. THEN *t the end of the text. 

is another name for ENDIF. Both 
names are aupported In flg-FORTH. See 
also IF and ELSE. 

FORTH INTEREST GROUP RO. Box 1105 San Carlos, Ca. 94070 



FSHCE 



FILL 



FIRST 



FID 



FORGET 



FORTH 



HERE 



addr I 

A user variable containing en 
address below which FORGETtlng is 
trapped. To forget below this point 
Che user auit alter the contcnti of 
FENCE. 

addr q u a n b 

Fill laasr; at Che addreas vlth the 
specified quantity of bytes b. 

n 

A conatant that laavaa the addreaa 
of tha first (lowest) block buffer. 



al of number 



addr 

A uaer variable for contrc . 
output field width. Presently un- 
used in fig-FORTH. 

E.LO 
Executed in the fore: 

FORGET cccc 
Deletes definition named cccc from 
the dictionary with all entries 
physically following it. In fig- 
FORTH, an error message will occur if 
the CURRENT and CONTEXT vocabularies 
are not currently tha sane. 

P.L1 

The nine of the primary vocabulary. 
Execution Bakes FORTH the CONTEXT 
vocabulary. Until additional user 
vocabularies are defined, new uaer 
definitions become a part of FORTE. 
FORTH ia immediate, ao it will exec- 
ute during the creation of a colon- 
definition, to eelect this vocabulary 
at compile time. 

addr LO 

Leave the address of tha next avail- 
able dictionary location. 



HEX 1,0 

Set the numeric converaion baaa to 
sixteen (hexadecimal). 

BLD addr LO 

A uaer variable that holde the addr- 
ess of the lateat character of text 
during numeric output conversion. 

HOLD c LO 

Daed between <# and t> to insert 
an aacil character into a pictured 
numeric output string. 
e.g. 2E BOLD vill place a 
decimal point. 

1 n C.LO 

Daed within a DO-LOOP to copy tha 
loop index to the stack. Other 
use is implementation dependant. 
See R. 

ID. addr 

Print a definition's name from Its 
name field address. 

IF f (run-time) 

addr n (coepile) P.C2.L0 

Occurs is a colon-definition in form: 

IF (tp) ... ENDIF 

IF (tp) ... ELSE (f p) ... ENDIF 
At run-time, IF selects execution 
based on a boolean flag. If f is 
true (non-xero), execution continues 
ahead thru the true part. If f If 
false (zero), execution skips till 
Just after ELSE to execute the false 
part. After either part, execution 
resumes after ENDIF. ELSE and its 
false part are optional.; if missing, 
false execution skips to Just after 
ENDIF. 



FORTH INTEREST GROUP 



R0. Box 1105 



San Carlos, Ca. 94070 



At complle-t ins IF conpllta OBRAHCH 
and reserves space for an offaet 
at addr, addr and n are used later 
for resolution of the offset and 
e rror testing. 



IKTBRJRET 



IMMEDIATE 



Mark the aost resently made definit- 
ion so that vhen encountered at 
compile tine, it Kill be executed 
rather than being compiled. I.e. the 
precedence bit in its header is set. 
This Bethod allows definitions to 

handle unusual compiling situations 
rather than build the* into the 
fundamental compiler. The user may 
force compilation of an immediate 
definition by proceeding it with 
[COMPILE) . 



the outer text 1 
sequentially «i« 
text from the 1 
or disc) dependi 
word name cannot 
s search of COKT 
it is converted 
to the current b 
ing, so error me 
name with > " ?" 
Text Input will 
the convention f 
point la found a 
a double number 
The decimal poin 
pose than to for 
See NUMBER. 



nterpreter which 
cutes or compiles 
put stream (terminal 
ng on STATS. If the 

be found after 
EXT and then CURRENT 
to a number according 
aae. That also fail- 
ssage ftchoing the 

1 will be given, 
be taken according to 
or WORD. If a decimal 
s part of a number, 
value will be left, 
t has no other pur- 
ee this action. 



18 addr L0 

A user variable containing the byte 
offset within the current input text 
buffer (terminal or dlac) from which 
the next text will be accepted. WORD 
uses and moves the value of IN. 

IBD2X from to 

Print the first line of each ecreen 
over the range from, to. This is 
used to view the comment lines of an 
area of text on disc screens. 



Leave the ascii value of the next 
terminal key struck. 

addr 

Leave the name field address of the 
topmost word in the CURRENT vocabul- 
ary. 



C.LO 
Force termination of a DO-LOOP at the 
next opportunity by setting the loop 
limit equal to the current value of 
the index. The index itself remalna 
unchanged, and execution prodeede 
normally until LOOP or +LOOP is 
encountered. 



FORTH INTEREST GROUP R 0. Box 1105 



San Carlos, Ca. 94070 



pfa lfa 

Convert the parameter field address 
of a dictionary definition to its 
link field address. 



d LO 

Begin interpretation of screen n. 
Loading will terminate at the end of 
the screen or at ; S . See ; S and --> • 



LITERAL 



A constant leaving the address Just 
above the highest memory svailable 
for a diac buffer. Usually this is 
the highest system memory. 

n LO 

Display the aacii text of screen n 
on the selected output device. SCR 
contains the screen number during, and 
after this process. 

n C2.L0 

Within a colon-definition, LIT is 
automatically compiled before each 
16 bit literal number encountered in 
input text. Later execution of LIT 
causes the contents of the Kit 
dictionary address to be pushed to 
the b t ack . 

n (compiling) P,C2,L0 

If compiling, then compile the stack 
value n as « lc bit literal. This 
definition is immediate so that it 
will execute during a colon defin- 
ition. The intended use la: 

: xxx [ calculate ] LITERAL ; 
Compilation is suspended for the 
compile time calculctloa of a value. 
Compilation is reusumed and L ITE&AL 
compiles this value. 



M/ 



•ddr n (compiling) P,C2,L0 

Occur* In a colon-definition In form: 

DO ... LOOP 
At run-time, LOOP selectively cont" 
rola branching back to the correspon- 
ding DO baaed on the loop Index and 
limit. The loop index ta Incremented 
by one and compared to the limit. The 
branch back to DO occur! until the 
Index equals or exceeds the limit; 
at that time, the parametera are 
discarded and execution continues 
ahead. 

At complle-tlrae , LOOP complies (LOOP) 
and uses addr to calculate an offset 
to DC. n Is used for error testing. 

nl n2 d 

A mixed magnitude math operation 
which Iiivii the double number signed 
product of tvo signed number. 

A nl n2 n3 

A mixed magnitude math operator vhlch 
leaves the signed remainder n2 and 
signed quotient n3, from a double 
cumber dividend and divisor nl. The 
remainder takes its sign from the 
d ividend . 



FORTH INTEREST GROUP R 0. Box 1105 



San Carlos, Ca. 94070 



MESSAGE 



M/MOD udl u2 u3 ud4 MOVE addrl addr2 n 

An unsigned nixed magnitude math Hove the contents of n memory cell" 

operation which leaves • double (16 bit contents) beginning at addrl 

quotient ud4 and remainder u3, from Into n cjJ1« beginning at addr2. 

a double dividend ud 1 and aingle The contents of addrl la moved first. 

divisor u2. ThiB definition 1» appropriate on 

on word addressing computers. 
MAX nl n2 max LO 

Leave the greater of two numbere. NEXT 

This Is the inner interpreter that 
n uses the Interpretive pointer IP to 

Print on the selected output device execute complied Forth definitions, 

the text of line n relative to screen It Is not directly executed but is 

4 of drive 0. n may be positive or the return point for all code pro- 

negative. MESSAGE may be used to ceedures. It sets by fetching the 

print incidental text such as report address pointed by IP, storing this 

headers. If WARNING is sero, the _ value In register V. It then jumps 

message will simply be printed as to the address pointed to by the 

a number (disc un-available ) . address pointed to by W. W points to 

the code field of a definition which 

MIH nl n? sin LO contains the address of the code 

Leave the smaller of two numbers. which executes for that definition. 

This usage of Indirect threaded code 

MINDS nl n2 LO ls a ma J or contributor to the power. 

Leave the two's complement of a portability, and extensibility of 

number. Forth. Locations of IP and W are 

computer specific. 



MOD nl n2 mod LO 

Leave the remainder of nl/n2, with 



pfa nfa 



the same sign aa nl. Convert the parameter field addreaa 

of a definition to its name field. 
MOM 

Eslt to the system monitor, leaving NUMBER addr d 

a re-entry to forth, if possible- Convert a character string left at 

addr with a preceedlng count, to 
a signed double nuober, using the 
current numeric base. If a decimal 
point is encountered in the text, its 

FORTH INTEREST GROUP R 0. Box 1105 San Carlos, Ca. 94070 



position will be given in D P L , but 
no other effect occurs. If numeric 
conversion is not possible, an error 
message will be given. 

OFFSET sddr 

A user variable which nay contain 
a block offset to disc drives. The 
contents of OFFSET is added to the 
stack number by BLOCK. Messages 
by MESSAGE are independent of OFFSET. 
See BLOCK, DRO, DR1, MESSAGE. 

OR nl n2 — or LO 

Leave the bit-wise logical or of two 
16 bit va lues. 

OUT addr 

A user variable that contains a valua 
incremented by EMIT. The user Bay 
alter and examine ODT to control 
display formating. 

OVER nl n2 nl n2 nl LO 

Copy the second stack value, placing 
it aa the new top. 

PAD addr LO 

Leave the address of the text output 
buffer, which is a fixed offset above 
HERE. 

PFA nfa pfa 

Convert the name field address of 
a compiled definition to its para- 
meter field address. 



POP 



PDT 



QDERY 



The code sequence to remove a stack 
value and return to NEXT. POP is 
not directly executable, but is a 
Forth re-entry point after machine 
code . 

.addr 

A variable containing the address of 
the disc buffer moat recently ref- 
erenced. The UPDATE command narks 
thia buffer to be later written to 
disc. 



Thia code sequence puahea machine 
registers to the computation stack 
and returns to NEXT. It la not 
directly executable, but is a Forth 
re-entry point after machine code. 



This code sequence stores machine 
register contents over the topmost 

computation stack value and returns 
to NEXT. It is not directly exec- 
utable, but Is a Forth re-entry point 
after machine code. 



Input 80 characters of text (or until 
a "return") from the operators 
terminal. Text is positioned at the 
address contained in TIB with IK 
a e t to se ro. 



FORTH INTEREST GROUP RO. Box 1105 



San Carlos, Ca. 94070 



QOIT 



&* 



Clear th* return stack, stop cocpil- 
ation, end return control to the 
operators terminal. Ho image 
Is given. 

--- n 
Copy the top of the return stack to 
the computation stack* 

--- addr 

A user variable which say contain 
the location of an editing cursor, 
or other file related function. 

nddr b 1 k f 

The fig- FORTH standard disr r e p. d - 
writ? MnVape. addr gpecifieB the 
source or destination block buffer, 
b 1 k is the sequential number of 
the referenced block; and f is a 
flag for f - write and f-1 read. 
R / W determines the location on nses 
storage, per forms the read-write and 
performs any error checking. 



n LO 

Remove the top value from the return 

stack and leave it on the computation 
s tack . See >R and R . 



addr t 

A user variable containing the 
initial location of the return stack. 
Pronounced R-zero. See RP I 



SO 



addr n (compiling) P,C2 

Used within a colon-definition in the 
form: 

BEGIN . . . WHILE . . . REPEAT 
At run-time, REPEAT forces an 
unconditional branch back to Just 
after the correapoinding BEGIN. 

At compile-tlme, REPEAT compiles 
BRANCH and the offset from HERE to 
addr. n ia used for error testing. 

nl n2 n3 n2 n3 nl LO 

Rotate the top three values on the 
stack, bringing the third to the top. 



A computer dependent proceedure to 
initialize the return stack pointer 
from user variable RO. 



Sign extend a single number to form 
a double numb e r . 

addr U 

A user variable that contains the ' 
initial value for the stack pointer. 
Pronounced S-zero. See SP! 

addr u 

A user variable containing the screen 
number most recently reference by 

LIST. 



FORTH INTEREST GROUP 



RO. Box 1105 



San Carlos, Ca. 94070 



SIGN n d d t LO STATE addr LO.U 

Stores an ascii "-" sign Juet before A user variable containg the compil- 

a converted numeric output string ation state. A non-zero value 

in the text output buffer when n is indicates compilation. The value 

negative. n is discarded, but double itself nay be implementation depend- 

number d is maintained. Must be ent. 

used between <# and 0>. 

SWAP nl n2 n2 nl LO 

SMUD(E Exchange the top tvo values on the 

Used during word definition to toggle stack. 
the "nrnudge bit" in a definitions' 

name field. This pi events an un- TA^K 

completed definition from being found A nc .- ope r a t i on word which can mark; 

during dictionary searches, until _,_ . - . ,, 

r , the boundary between applications. 

compiling is completed without error. „ y forgettlng TASK and re - C omp i 1 lng . 

an application can be discarded in 

SP! its entirety. 
A computer dependent proceedure to 
initialize the stack pointer from 

s0 THEN P.CO.LO 

An alias for ENDIF. 

SPg addr 

A computer dependent proceedure to TIB addr U 

return the address of the stack A user variable containing the addr- 

positlon to the top of the stack, ess of the terminal input buffer. 



as it was before SP@ was executed, 
(e.g. 1 2 SP? g would 



addr b 



type 2 2 1) Complement the contents of addr by 

the bit pattern b. 
SPACE LO 

Transmit an aacii blank to the output TRAVERSE addrl n addr2 

dev ce. Move across the name field of a 

fig-FORTH variable length name field. 
SPACES n LO addrl is the address of either the 

Transmit n aacii blanks to the output length byte or the last letter. 

device. If n"l, the motion is toward hi mem- 

ory; if n"-l, the motion is toward 
low memory. The addr2 resulting is 
address of the other end of the name. 

FORTH INTEREST GROUP R 0. Box 1105 San Carlos, Ca. 94070 



Bcr At co mp lie-time, UNTIL compiles 

Display on the select rd output device (0 BRANCH) and an offset froa HERE 

the three acreenB which include that to addr. n is used for error testa. 

numbered scr, begin in g with a screen 

evenly divisible by three. Output 

1b luitable for source text records, UPDATE L0 

and includes a reference line at the Marks the most recently referenced 

bottom taken from line 15 of screenA. block (pointed to by PREV) is 

altered. The block will subsequently 
be transferred automatically to disc 

addr count — L0 should it. buffer be required for 

Transmit count characters from addr storage of a different block. 
to the selected output device. 

USE addr 

u l u 2 u( j * variable containing the address of 

t «,„<,. »k„ „»<„ j j v. i v. the block buffer to use next, as the 
Leave the unsigned double number * 

product of two unsigned numbers. least recently written. 



U7 ud ul --- u2 u3 u5tK 

Leave the unsigned remainder u 2 and 
unsigned quotient u3 from the unsign- 
ed double dividend ud and unsigned _._ . .. , , , „ . 
,, . , " The parameter field of cccc contains 
divisorul. , . , 



n L0 

A defining vord used in the form: 

n USER cccc 
which creates a user variable cccc. 



UNTIL f (run-tine) 



as a fixed offset relative to 

the user pointer register DP for 

this user variable. When cccc is 



addr n — (compile) P.C2.L0 1 a ter execu t ed , it places the sum of 

Occurs within a colon-definition in "' ottset and the user are. base 

the form: address on the stack as the storage 

BEGIN ... UNTIL address of that particular variable. 

At run-time, UNTIL controls the cond- 
itional branch back to the corres- 
ponding BEGIN. If f is false, exec- 
ution returns to Just after BEGIN; 
if true, execution continues ahead. 



FORTH INTEREST GROUP R 0. Box 1105 San Carlos, Ca. 94070 



var ; abl e 



A defining word used in rhe form: 

n V A & 1 A h L E cccc 
Wher. VARIABLE is executed, it creates 
the definition cccc with its para- 
meter field initialized to n . When 
cccc is later executed, the address 
of its parameter field (containing n) 
is left on the stack, bo that a fetch 
or store m&y a c c e a s this location. 

VOC-LINK addr U 

A user variable containing the addr- 
ess of a field In the definition of 
the moat recently created vocabulary. 
All vocabulary names are linked by 
these fields to allow control for 
FORGETting thru naultiple vocabularys. 

VOCABULARY E,L 

A defining word used in the form: 

VOCABULARY cccc 
to create a vocabulary definition 
cccc. Subsequent use of cccc will 
make it the CONTEXT vocabulary which 
is searched first by INTERPRET. The 
sequence "cccc DEFINITIONS" will 
also make cccc the CURRENT vocabulary 
into which new definitiona are 
placed. 

In fig-FORTH, cccc will be so chained 
as to include all definitions of the 
vocabulary in which cccc is itself 
defined- All vocabularyB ulitmately 
chain to Forth. By convention, 
vocabulary names are to be declared 
IMMEDIATE. See VOC-LINK. 



E,LU VLIST 



List the names of the definitions in 
the context vocabulary. "Break" will 
terminate the listing. 



WARNING 



WHILE 



3 1 ue 



addr 

A user variable containing a > 
controlling messages. If « 1 
disc is present, and screen 4 of 
drive is the base location for 
messages. If - 0, no disc is present 
and messages will be presented by 
number. If - -1, execute (ABORT) for 
a user specified proceedure. 
See MESSAGE, ERROR. 



P,C2 
the 



f (run-time) 

adl nl adl nl ad2 n2 

Occurs in a colon-definition 
f ortD : 

BEGIN ... WHILE (tp) ... REPEAT 
At run-time, WHILE selects condition- 
al execution based on boolean flag f. 
If f is true (non-zero), WHILE cont- 
intues execution of the true part 
thru to REPEAT, which then branches 
back to BEGIN. If f is false (zero), 
execution skips to just after REPEAT, 
exiting the structure. 

At compile time, WHILE emplaces 
(OBRANCH) and leaves ad2 of the res- 
erved offset. The stack values will 
be resolved by REPEAT. 



FORTH INTEREST GROUP 



R0. Box 1105 



San Carlos, Ca. 94070 



WIDTH a d d r U 

In flg-FORTK, a user vcrlablc cont- 
aining the maximum number of letttfi 

saved in * *■ - - i - . « ~ _ -c - 

ons' nattr. It oust be 1 

Tho 



compilation of 
definitions' naae. It oust be 1 thru 
31 , with a default value of 3 1. Tho 
name character count and its natural 
.v.-ar-roT-c oro. saved, up to the 

The value may be 
time within the above 



chara 
val 

changed 



iters are 

i n WIDTH, 
any 



liml r. s . 



Read the next text characters from 
the Input stream being interpreted, 
until a delimiter c is found, storing 
the packed character string beglning 
at the dictionary buffer HERE. WORD 
leaves the character count in the 
first byte, the characters, and enda 
with two or aon blanks. Leading 
occurances of-c are Ignored. If BLK 
is zero, text is taken from the 
tertainal input buffer, otherwise from 
the disc block stored in BLK. 
See BLK, IN. 



n 1 n2 xor LI 

Leave the bitviee logical exclusive- 
or of two va lues . 



I P. LI 

Used in a colon-definition in form: 

: xxx [ words ) tore ; 
Suspend compilation. The words after 
E are executed, not compiled. This 
allows calculation or compilation 
exceptions before resuming compil- 
ation with ]. Sea LITERAL, ]• 

^COMPILE] P,C 

Used in a colon-definition In form: 

: xxx [COKPILEJ FORTH ; 
[COMPILE] will force the compilation 
of an immediate defininltlon, 
that would otherwise execute 
during compilation. The above 
example will select the FORTH 
vocabulary when xxx executes, rather 

than at compile time. 



This is pseudonym for the "null" 

or dictionary entry for a name of 

one character of ascii null. It 

is the execution proceedure to term- 

inate interpretation of a line of 

text from the terminal or within 

a disc buffer, as both buffers always 

have a null at the end. 



LI 
Resume compilation, to the completion 
of a colon-definition. See [. 



FORTH INTEREST GROUP R 0. Box 1105 



San Carlos, Ca. 94070 



COPYRIGHT NOTICE 

Copyright (C) 1982 by Human Engineered Software. All 
rights reserved. No part of this publication may be 
reproduced in whole or in part without the prior 
written permission of HES. Unauthorized copying or 
transmitting of this copyrighted software on any 
media is strictly prohibited. 

Although we make every attempt to verify the accuray 
of this document, we cannot assume any liability for 
errors or emissions. No warranty or other guarantee 
can be given as to the accuracy or suitability of 
this software for a particular purpose, nor can we 
be liable for any loss or damage arising from the 
use of the same. 



HS 



Human Engineered Software 
71 Park Lane 

Brisbane, California 94005 
Telephone 415-468-4110 



HS 



■iM ■■■■ 



VIC FORTH 



by Tom Zimmer 



C301 




© 1982 Human Engineered Software